Sunshine 游戏串流应用管理快速上手指南手把手配置你的第一个可串流游戏【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine刚把 Sunshine 装好、兴冲冲地在 Moonlight 里点开客户端时很多人会发现一个尴尬的现实应用列表里只有一个孤零零的Desktop。想玩《赛博朋克2077》、想进 Steam 大屏幕模式全都无从下手。Sunshine 作为一款自托管的游戏串流服务器本身只是个管道工把游戏进程接入视频编码再推给 Moonlight真正决定你能串流什么、怎么串流的是它底下的应用管理模块。这篇文章就带你把这个模块彻底摸透。读完本文你将获得一套 3 分钟就能跑通的最简添加流程对 apps.json 配置文件中每个关键字段的通俗解释三种启动方式的适用场景判断方法cmd / detached / auto-detach利用环境变量做分辨率随客户端自动变化的进阶配置五类高频翻车场景的排查思路先把遥控器理解清楚应用管理到底管什么如果把 Sunshine 比作一台带遥控器的电视那么应用管理就是遥控器上那些自定义按钮每个按钮对应一个游戏按下去之后Sunshine 帮你完成切分辨率 → 启动游戏 → 推流 → 退出后复原分辨率这一整套动作。Sunshine 的应用管理核心其实只有两样东西一个配置文件默认叫apps.json与主配置文件sunshine.conf放在同一目录。里面用 JSON 数组登记每一个应用。一个网页界面在浏览器打开https://localhost:47990首次登录会要求你设置用户名和密码务必记牢顶栏的 Applications 页面就是可视化管理入口。两者是所见即所得的关系你在网页上点几下添加的应用最终都会写进 apps.json反过来你手动改好 apps.json 并重启 Sunshine网页上也会同步显示。所以先学会在网页上操作再回头理解 JSON 内容是最平滑的学习路径。3 分钟极速上手添加第一个游戏我们先用最简单的方式让一个游戏能跑起来之后再去理解背后原理。第一步登录 Web UI点击顶栏 Applications 进入应用列表然后点击 Add 新建一个应用。第二步填写三个必填项。以 Steam 里的《求生之路2》AppID 550为例表单字段填入内容说明Application NameLeft 4 Dead 2会显示在 Moonlight 客户端里最好用英文或拼音避免乱码Command Prepations留空稍后讲解这里先不管Detached Commandssteam://rungameid/550让 Steam 去启动游戏Sunshine 不等它结束第三步点 Save回到 Moonlight 客户端刷新应用列表你就能看到新出现的 Left 4 Dead 2点击即可串流。如果这三步走完游戏成功推流恭喜你你已经掌握了 80% 的操作。剩下 20% 的价值在于搞清楚为什么 Steam 游戏要用 Detached 而不是普通 Command——这正是很多新手第一次配游戏就翻车的根源。深度拆解三条启动通道对应三种脾气Sunshine 给每个应用提供三条启动通道理解它们就像理解三种不同性格的客人通道一cmd —— 进门就坐不聊不走cmd是最直接的启动方式Sunshine 启动该命令持续盯住这个进程一旦它退出串流会话立刻结束。适合那些游戏进程 游戏本体的情况比如直接运行game.exe或.sh脚本。{ name: My Game, cmd: C:\\Games\\MyGame\\game.exe, working-dir: C:\\Games\\MyGame, image-path: mygame.png }注意两点working-dir是工作目录不填则默认取可执行文件所在目录Windows 路径里的反斜杠在 JSON 中要写成\\。通道二detached —— 打个招呼就走不等他坐detached里的命令被启动后Sunshine 不追踪它的生命周期串流会话与命令是否退出互不干扰。这专门用来对付那些壳进程会自己退出的启动器——最典型的就是 Steam你用steam://rungameid/550唤起 Steam 后那个启动进程很快就结束如果放在cmd里串流会当场断开。放进detached就万事大吉。通道三auto-detach —— 先等等看他走了我再撒手auto-detach是个自动判断开关开启后Sunshine 先像cmd一样等待启动进程如果进程在短时间默认约 5 秒内仍在运行就转为脱离跟踪如果很快退出则保持连接。这是解决有些游戏启动器跑得慢容易被误判退出的平衡方案Steam 游戏官方默认配置里就同时用了detachedauto-detach: true。三条通道的取舍可以记成一句口诀程序自己就是本体用 cmd程序是传话筒用 detached拿不准就用 auto-detach 兜底。理解 apps.json一个应用就是一张配置卡在 Web UI 里点出的每个应用最终都以 JSON 对象的形式躺在 apps.json 中。逐个字段认识它你就能跳出网页表单的束缚做出更灵活的配置字段类型作用示例namestring应用显示名Moonlight 里看到的名字Cyberpunk 2077cmdstring/array主启动命令game.exedetachedarray脱离式启动命令可多条[steam://rungameid/1091500]prep-cmdarray预备命令组含 do / undo 两段[{do:...,undo:...}]working-dirstring工作目录C:\\Games\\Cyberpunkimage-pathstring应用图标路径cyberpunk.pngauto-detachbool是否自动脱离跟踪truewait-allbool是否等待所有进程结束再判断退出trueelevatedbool是否以管理员权限运行Windows 服务模式falseexclude-global-prep-cmdbool是否跳过全局预备命令trueoutputstring命令日志输出文件路径game.logenvobject附加环境变量仅能直接改文件{MY_VAR:1}以仓库自带的 Windows 版默认 apps.json 为例你能看到最典型的组合{ env: {}, 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 } ] }注意 Desktop 这个特殊应用它没有任何命令作用是只推流桌面、不启动任何程序。如果你不小心删了它新建一个名为 Desktop、图标为desktop.png的应用就能找回来。预备命令进门安检与出门复原prep-cmd是整个应用管理中最有威力的字段也是实现体验升级的关键。它由一对命令组成do应用启动前执行像进门安检失败则中止本次启动undo串流结束后执行像离场收拾用来恢复现场。它最常见的用途是按客户端请求动态切换分辨率。Sunshine 会把客户端的请求以环境变量的形式传给预备命令你可以随时取用环境变量含义示例值SUNSHINE_CLIENT_WIDTH客户端请求的画面宽度1920SUNSHINE_CLIENT_HEIGHT客户端请求的画面高度1080SUNSHINE_CLIENT_FPS客户端请求的帧率60SUNSHINE_CLIENT_HDR客户端是否请求 HDRtrue / falseSUNSHINE_APP_NAME当前应用名Cyberpunk 2077SUNSHINE_APP_ID当前应用 ID12345Linux 的 X11 环境下一份跟随客户端切分辨率的配置长这样{ name: Game with Adaptive Resolution, cmd: game.sh, prep-cmd: [ { do: sh -c \xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}\, undo: xrandr --output HDMI-1 --mode 3840x2160 --rate 120 } ] }Windows 上同理只是换成了 QRes 之类的命令行工具并把环境变量写成%SUNSHINE_CLIENT_WIDTH%的形式。注意undo里的数值是写死的——它代表串流结束要恢复成的原始分辨率与客户端无关。此外prep-cmd还支持elevated子字段让某条预备命令以管理员权限执行仅 Windows 服务安装模式有效。如果你要配合反作弊系统运行需要提权的游戏可以把整条cmd的elevated设为true。进阶玩法三个让效率翻倍的技巧技巧一全局预备命令一次配置处处生效除了每个应用自己的prep-cmdSunshine 在配置里还支持global_prep_cmd全局预备命令它会在每个应用启动前后执行。适合放所有游戏都要做的准备工作比如关闭显示器省电策略、同步系统时钟。若某个应用不需要把它的exclude-global-prep-cmd设为true即可跳过。技巧二环境变量传参一套模板多种应用apps.json 顶层支持env对象给所有应用注入自定义环境变量单个应用也能通过env覆盖。你可以在命令里用$(HOME)引用主目录$$会被替换成$让同一份配置在不同机器上迁移而无需改路径。比如把游戏放在$(HOME)/Games下cmd写成$(HOME)/Games/MyGame/start.sh换台电脑也不用改。技巧三手工编辑后如何安全生效修改 apps.json 后需要重启 Sunshine 服务才能重新加载。Windows 上在系统托盘图标右键选择重启Linux 上用systemctl --user restart sunshine或对应发行版的启停命令。改之前先备份原文件这是任何配置文件操作的铁律。常见坑位五类高频翻车现场与对策坑位一点开游戏串流立刻断开。八成是启动命令放在了cmd里而那个程序其实是个传话筒Steam、Epic 启动器都算。把命令移到detached或者开启auto-detach问题基本消失。坑位二Steam 唤起了但游戏没进。steam://rungameid/AppID要求 Steam 客户端已登录且 AppID 正确。先在主机上手动确认steam://rungameid/550能正常拉起游戏再回来检查配置。另外 Flatpak 安装的 Sunshine 必须给命令加flatpak-spawn --host前缀才能触达宿主机否则命令会被沙箱吞掉。坑位三Windows 下路径老是报错。JSON 里反斜杠必须写成\\路径含空格时必须加引号例如cmd: \C:\\Program Files (x86)\\Steam\\steam.exe\。偷懒的办法是能用 URI 启动如steam://、com.epicgames.launcher://就优先用 URI官方都推荐这种方式最省心。坑位四串流中鼠标键盘没反应。这通常不是应用配置问题而是输入权限问题。Linux 上把运行 Sunshine 的用户加入input组sudo usermod -a -G input 你的用户名然后重新登录Windows 上检查虚拟手柄驱动如 ViGEmBus是否安装。坑位五分辨率不对画面拉伸变形。检查预备命令里的xrandr/ QRes 命令是否真的执行成功以及目标显示器是否支持该模式。iOS、macOS 客户端常请求非标准分辨率需要先用cvt生成新模式再应用而不是指望显示器原生支持。下一步从能跑到跑得舒服回顾一下这条学习路径先用 Web UI 三步添加第一个 Steam 游戏再理解三条启动通道的脾气接着读透 apps.json 的字段然后用预备命令实现分辨率自适应最后避开五个高频坑。你已经从只会看 Desktop进化到能徒手写配置的阶段了。接下来建议你做三件事打开https://localhost:47990把刚才的配置再点一遍对照本文字段表逐个确认到 Troubleshooting 页面看看日志熟悉正常启动时日志长什么样出问题时能更快定位把你最常玩的 3~5 个游戏全部添加完并为它们配上封面图——一份打理得当的应用列表是流畅串流体验的一半。记住Sunshine 的应用管理不是配一次就完事而是一个随你的游戏库同步生长的清单。把这块配置练熟你离随时随地无缝开玩就只差一个 Moonlight 客户端了。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考