Sunshine 游戏库管理终极指南：应用添加与配置完整上手清单

Sunshine 游戏库管理终极指南应用添加与配置完整上手清单【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine深夜十一点你窝在沙发上用 Moonlight 客户端连回书房里的电脑想开一局刚买的 3A 大作。电脑屏幕上 Sunshine 已经显示已连接可点了半天游戏图标另一端却毫无反应——Steam 没启动、分辨率没切换、串流画面里只有一个孤零零的桌面。是不是很熟悉大多数 Sunshine 新手的第一次翻车都不是坏在串流本身而是坏在应用添加与配置这一步游戏该用 URI 启动还是直接调 exe为什么游戏一启动串流就断分辨率怎么跟着客户端自动切换读完这篇 Sunshine 应用管理实操指南你会彻底搞懂 Sunshine 的应用添加与配置机制能独立完成 Windows / Linux / macOS 上各类游戏的接入并会用预备命令prep-cmd实现分辨率自动适配、环境准备等进阶玩法。全程手把手每一个示例都能直接复制使用。一分钟看懂Sunshine 应用系统是怎么运转的在动手之前先用最短的时间建立认知。Sunshine 的应用管理核心就三层你在 Web UI 填写的应用表单 ↓ 保存 apps.json 配置文件核心相当于游戏启动说明书 ↓ 客户端发起串流请求 应用执行引擎读取说明书 → 依次执行预备命令 → 启动游戏Web UI登录https://localhost:47990后在 Applications 页面操作所有改动最终都写入配置文件apps.json真实的配置文件位于 Sunshine 配置目录Windows 为%SUNSHINE_CONFIG_DIR%Linux 为~/.config/sunshine附近你可以把它理解为游戏启动说明书集合应用执行引擎串流连接建立后引擎按预备命令 do → 启动主命令 → 会话结束时执行 undo的顺序执行相当于给每个游戏定制了一套开机/关机脚本。项目内置的默认配置src_assets下的apps.json就是最好的入门教材Windows 版长这样{ apps: [ { name: Desktop, image-path: desktop.png }, { name: Steam Big Picture, cmd: steam://open/bigpicture, prep-cmd: [ { do: , undo: steam://close/bigpicture } ], auto-detach: true, wait-all: true, image-path: steam.png } ] }一个应用条目里的每个字段都对应 Web UI 表单里的一项先记住这张对照表后面所有示例都建立在它之上字段JSONWeb UI 位置作用nameApplication Name应用在 Moonlight 客户端里显示的名称cmdCommands主启动命令可多条detachedDetached Commands分离式命令游戏由外部进程托管如 Steamprep-cmdCommand Preparations预备命令do在启动前执行undo在结束时回滚working-dirWorking Directory工作目录不填则默认取主命令所在目录image-pathImage应用图标auto-detachAuto Detach主命令退出后是否立即判定游戏结束wait-allWait All是否等所有命令都退出才结束会话elevatedElevated仅 Windows以管理员权限启动服务模式免 UAC 弹窗outputOutput日志文件路径排错利器记住这张表你就可以进入实操了。第一站最快配置路径先跑通一个最小可运行示例万事开头难所以我们的第一站故意选最小只添加一个Desktop桌面应用。它没有任何命令作用就是把整块屏幕当成应用串流出去——用来验证链路是否畅通成本最低。在 Web UI 的 Applications 页面点击Add New只填两项字段值Application NameDesktopImage可选填desktop.png或留空保存后重启 Moonlight 客户端页面提示Applications are refreshed only when Client is restarted此时你就能看到 Desktop 卡片点击即可串流桌面。为什么先跑这个因为 Desktop 不涉及任何命令执行如果它都串不起来问题出在串流链路本身如果它能串而游戏不能问题就出在应用配置上——这帮你把排查范围立刻缩小了一半。第二站基础版 vs 进阶版两类游戏的分层配置跑通桌面后轮到真正的游戏。这里用基础版 / 进阶版的对比来讲比按平台机械罗列更实用——你会发现同一个游戏从能启动到体验完善中间只差几条命令。Steam 游戏从能进游戏到退出不残留基础版最快能用用 URI 方案。Steam 游戏启动时会自我更新、杀掉原进程再重启所以绝不能放在cmd里主命令一退串流就判定游戏结束必须放进Detached Commands字段值Application NameCyberpunk 2077Detached Commandssteam://rungameid/10915001091500 是该游戏的 AppID各平台把steam://rungameid/1091500换成对应写法即可Linux / FreeBSD 用setsid steam steam://rungameid/1091500macOS 用open steam://rungameid/1091500。进阶版体验完整再补上预备命令让会话结束时自动关掉大图模式不给系统留孤儿进程字段值Detached Commandssteam://rungameid/1091500Prep-Cmd → Undosteam://close/bigpictureLinux 为setsid steam steam://close/bigpictureAuto Detach✅ 勾选取舍说明URI 方案在不同游戏之间表现最一致是所有平台官方推荐的首选。只有当 URI 方案失效比如某些特殊平台或需要带参启动时才降级用二进制直启见下面的 Epic 示例。Epic 游戏URI 与二进制的两条路Epic 游戏有两种接法各有用武之地方案 AURI 方式推荐。把启动地址填进 Commands{ name: Surviving Mars, cmd: com.epicgames.launcher://apps/替换为游戏专属ID?actionlaunchsilenttrue }方案 B直接调用 exe进阶。当某些游戏 URI 无效或你想跳过 Epic 启动器时{ name: Surviving Mars, cmd: MarsEpic.exe, working-dir: C:\\Program Files\\Epic Games\\SurvivingMars }注意这里特意写了working-dir不写工作目录时Sunshine 默认取主命令所在目录但如果你的 exe 需要相对路径读取资源文件工作目录填错就会导致游戏启动即崩溃。所以命令填完整绝对路径 工作目录留空等价于命令填相对路径 工作目录填对——二选一别都填错。进阶玩法预备命令让分辨率跟着客户端走游戏能启动了但分辨率不对——客户端请求 1080p主机还卡在 4K。这就是预备命令prep-cmd的主场串流开始前把主机显示器切到客户端请求的分辨率会话结束undo 把分辨率切回去。Sunshine 会在执行预备命令时注入客户端信息Windows 下用%SUNSHINE_CLIENT_WIDTH%这类写法Linux / macOS 下用${SUNSHINE_CLIENT_WIDTH}。各平台的最小可用示例平台Do启动时执行Undo结束时回滚WindowsQRes 工具cmd /C qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%qres.exe /x:3840 /y:2160 /r:120Linux X11xrandrsh -c xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}xrandr --output HDMI-1 --mode 3840x2160 --rate 120KDE Plasmakscreen-doctorsh -c kscreen-doctor output.HDMI-A-1.mode.${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}${SUNSHINE_CLIENT_FPS}kscreen-doctor output.HDMI-A-1.mode.3840x2160120macOSdisplayplacersh -c displayplacer \id:你的屏幕ID res:${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} hz:${SUNSHINE_CLIENT_FPS} scaling:on origin:(0,0) degree:0\displayplacer id:你的屏幕ID res:3840x2160 hz:120 scaling:on origin:(0,0) degree:0NVIDIA 显卡sh -c nvidia-settings -a CurrentMetaMode\HDMI-1: nvidia-auto-select { ViewPortIn${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}, ViewPortOut${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}00 }\nvidia-settings -a CurrentMetaModeHDMI-1: nvidia-auto-select { ViewPortIn3840x2160, ViewPortOut3840x216000 }三个注意事项显示器名称因会话而异X11 下可能是HDMI-1Wayland 下可能是HDMI-A-1用kscreen-doctor -o或xrandr列出真实名称xrandr 模式必须已存在默认模式表里没有客户端请求的分辨率时命令会失败macOS / iOS 客户端常用非标准分辨率需要先用脚本创建 mode 再切换Linux 下用 Flatpak 安装的 Sunshine所有命令都要加flatpak-spawn --host前缀沙箱无法直接触达宿主机。速查附录环境变量与常用字段一页纸这一节是随时回来查的索引实战时不必背遇到配置需求翻到这里即可。预备命令可用的环境变量环境变量含义示例值SUNSHINE_CLIENT_WIDTH客户端请求的宽度1920SUNSHINE_CLIENT_HEIGHT客户端请求的高度1080SUNSHINE_CLIENT_FPS客户端请求的帧率60SUNSHINE_CLIENT_HDR客户端是否请求 HDRtrue / falseSUNSHINE_APP_NAME当前串流的应用名Cyberpunk 2077SUNSHINE_APP_ID当前应用唯一标识12345冷门但好用的字段字段用途与提示exclude-global-prep-cmd设为true时跳过全局预备命令适合个别洁癖游戏elevated仅 Windows服务模式下免 UAC 弹窗以管理员运行对prep-cmd的 do / undo 也各自生效output指向日志文件游戏反复崩溃时这是第一手证据env顶层全局环境变量Linux 默认配置用它扩展了PATH例如PATH: $(PATH):$(HOME)/.local/bin踩坑清单三列式速查按图索骥遇到问题别慌按【现象 / 根因 / 处置】三列对号入座现象根因处置游戏一启动串流立刻断开主命令进程退出被判定为游戏结束改用detached分离式命令勾选auto-detach检查游戏是否有自更新杀进程行为Steam 常见启动器起来了游戏本体没起用了cmd但启动器是转发型进程换 URI 方案steam://rungameid/xxx或改用detached客户端分辨率与主机不一致缺分辨率切换命令在prep-cmd的 do / undo 里加分辨率切换见上文平台对照表命令执行失败但不知道原因预备命令报错被吞掉在应用里填output日志路径先手动在终端执行同一条命令验证鼠标键盘无响应Linux用户不在 input 组sudo usermod -a -G input 你的用户名重新登录生效Flatpak 版命令没有权限沙箱隔离命令无法触达宿主机所有命令加flatpak-spawn --host前缀Windows 游戏要管理员权限却弹 UAC普通方式启动无法提权勾选该命令的elevated选项需以服务方式运行 Sunshine默认即是配置体检清单交付前逐项打勾配置完别急着收工把这份清单过一遍——它同时充当最佳实践 优化建议客户端Moonlight重启后能看到新应用图标显示正常用detached启动 Steam / 启动器类应用而不是cmd分辨率能跟随客户端自动切换且会话结束后能恢复到原分辨率undo 生效串流结束回桌面没有残留的 steam / 游戏进程每个应用都配置了output日志路径方便日后排错用 Flatpak 安装的用户所有命令都已加flatpak-spawn --host图标使用轻量 PNG如steam.png、desktop.png避免大图拖慢列表加载定期备份apps.json换机 / 重装后一键恢复已实测一遍发起串流 → 进游戏 → 退出 → 回桌面全流程收束小结、下一步行动与延伸资源核心小结Sunshine 的应用添加与配置本质上就是为每个游戏写一张启动说明书——用cmd/detached决定怎么把游戏拉起来用prep-cmd的 do / undo 决定串流前后做什么准备和收尾用环境变量让命令感知客户端请求。URI 优先、分离式命令兜底、预备命令负责体验这三条主线足以覆盖九成场景。下一步行动现在就去执行——打开 Sunshine Web UI默认https://localhost:47990→ Applications → Add New先添加 Desktop 跑通链路再按本文的 Steam 进阶版配置你的第一款游戏最后给常用的游戏各配一条分辨率切换预备命令。完成后用 Moonlight 客户端完整串一次流。延伸资源想进一步深入可以翻阅项目文档中的官方应用示例docs/app_examples.md内含各平台完整配置或者查看配置项全解docs/configuration.md。如果对某个平台如 KDE Wayland 或 NVIDIA的分辨率切换还想看更多细节文中对应的命令组合就是最好的起点——把它替换成你显示器的真实名称你就已经出师了。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考