Sunshine 游戏库添加完整手册：十分钟配好你的第一个串流应用

Sunshine 游戏库添加完整手册十分钟配好你的第一个串流应用【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine把 Steam 里的游戏、Epic 商城的大作、甚至某个绿色免安装的 exe 一键变成可串流项目是 Sunshine自托管游戏串流服务器配合 Moonlight 客户端使用最核心也最常被问起的功能。这篇手册用清单推进的方式带你从零添加第一个游戏库条目并顺手解决启动即退出、黑屏、输入失灵这些高频麻烦。开工前先备齐这三样少走半小时弯路动手前请确认三件事缺任何一样后面都会犯难Sunshine 正在运行且你能在浏览器打开 Web UI默认地址 https://localhost:47990 首次需用终端输出的 PIN 码登录。Moonlight 客户端已完成配对能正常看到主机但还看不到任何可启动的应用。知道游戏怎么启动Steam 游戏的数字 ID在商店页 URL 末尾、Epic 游戏的启动 URI或可执行文件的完整路径。游戏条目统一存放在apps.json里路径与主配置文件同目录也可用配置项file_apps改成任意位置。所有增删改都能在 Web UI 的「应用」页完成无需手工编辑 JSON但理解 JSON 结构能帮你排查问题。做完这一步你手里有了打开 Web UI 的地址、配对好的客户端、以及游戏的启动信息后面每步都能直接落地。一张图看懂从点击到推流的完整链路apps.json本质是一个 JSON 数组每个条目描述一件事启动谁、启动前做什么准备、结束后如何还原。执行时流程如下关键就三点prep-cmd是成对的do启动前执行、undo结束后还原环境变量把客户端的屏幕参数实时告诉脚本detached表示命令一发出就算成功不用等它退出。做完这一步你建立了排查问题的思维模型——出任何怪问题先问一句这是 do 没执行、undo 没还原还是进程压根没起来。按这个最小配置加入你的第一个 Steam 游戏在 Web UI 的「添加应用」里填入下面内容这是覆盖 80% 场景的基础配方{ name: Surviving Mars, // Moonlight 里显示的名称 detached: [steam://rungameid/464920], // 用 URI 交给 Steam 启动不阻塞等待 auto-detach: true, // 子进程分裂后立即视为启动成功 image-path: steam.png // 封面图可留空使用内置占位图 }为什么用detached而不是cmd因为 Steam 启动时会先起一个自更新进程随后杀掉原进程再拉起真正的游戏如果 Sunshine 盯着cmd的进程树会发现游戏刚启动就退出直接结束会话。detached恰好绕开这个坑Linux/macOS 下只需把命令换成setsid steam steam://rungameid/464920或open steam://rungameid/464920。几个常用字段的作用一张表说清字段作用建议cmd直接执行的命令或 exe 路径游戏本体、无启动器的应用用它detached发出即返回的启动命令Steam/Epic 等平台游戏优先用它working-dir命令的工作目录不填则默认使用目标程序所在目录prep-cmd成对的 do/undo 预备命令分辨率、音频切换都靠它elevated以管理员权限启动仅 Windows需要管理员权限的反作弊游戏开启做完这一步你的 Moonlight 里已经出现第一个可点击的游戏图标串流会话能正常建立并维持。用预备命令把显示调成客户端想要的分辨率进阶场景客厅电视要求 4K、卧室平板只支持 1366×768Sunshine 默认不会替你切分辨率。此时用prep-cmd配合客户端环境变量在每次会话开始时自动调整显示模式结束后还原。Windows 下可用 nircmd也可换成任意支持命令行切分辨率的工具{ name: 自动适配分辨率的游戏, cmd: game.exe, prep-cmd: [ { do: nircmd.exe setdisplay %SUNSHINE_CLIENT_WIDTH% %SUNSHINE_CLIENT_HEIGHT% 32 %SUNSHINE_CLIENT_FPS%, undo: nircmd.exe setdisplay 2560 1440 32 144, // 还原回主机平时用的桌面模式 elevated: true } ] }Linux 桌面的写法思路相同X11 下把 do 换成sh -c xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}注意前提是该模式已存在不存在时需先用cvt生成新 mode 再--addmode完整脚本见官方应用示例文档。Wayland 下则对应wlr-xrandrwlroots 系或kscreen-doctorKDE。预备命令里可用的变量如下环境变量含义示例值SUNSHINE_CLIENT_WIDTH/HEIGHT客户端请求的宽高1920 / 1080SUNSHINE_CLIENT_FPS客户端请求的帧率60SUNSHINE_CLIENT_HDR客户端是否开启 HDRtrueSUNSHINE_APP_NAME/APP_ID当前应用名与编号Surviving Mars / 3SUNSHINE_CLIENT_AUDIO_CONFIGURATION客户端音频布局2.0 / 5.1 / 7.1做完这一步无论客户端什么分辨率游戏画面都会自动对齐串流观感与本地玩几乎一致。按这份清单排查启动即退出等四类麻烦现象点击后画面一闪会话立刻结束。原因cmd指向的是 Steam/Epic 这类会自我重启的启动器原始进程被杀Sunshine 误判游戏退出。对策改用detached并打开auto-detach或直接把命令填成游戏本体 exe。现象黑屏或画面被拉伸。原因显示器没有客户端请求的分辨率模式切换失败。对策先cvt生成并--addmode注册新模式再执行 do 命令确认 undo 里的模式确实存在。现象Flatpak 安装的 Sunshine 里预备命令完全不生效。原因Flatpak 沙箱隔离了宿主机命令。对策所有命令前缀flatpak-spawn --host例如flatpak-spawn --host setsid steam steam://open/bigpicture。现象画面正常但手柄/键盘毫无反应。原因权限或驱动问题。对策Linux 下把 Sunshine 运行用户加入input组sudo usermod -a -G input 用户名后重登Windows 下检查 ViGEmBus 虚拟手柄驱动是否已安装。做完这一步四类高频故障你都能自己定位到根因而不是反复重启 Sunshine 碰运气。记下这五条心得让游戏库长期好用平台游戏一律 URI 优先steam://、com.epicgames.launcher://...?actionlaunchsilenttrue比直接调 exe 更稳定不受版本更新影响。do 与 undo 必须对称do 切了分辨率undo 就要还原只写 do 不写 undo串流结束后主机桌面就赖在低分辨率回不去了。全局预备命令与单应用隔离公共操作如切音频设备放进global_prep_cmd个别应用不想执行时可设exclude-global-prep-cmd: true。给应用挂上日志output字段指向一个日志文件路径启动失败时直接看输出比猜快得多。封面图用 PNGimage-path支持自定义图标PNG 体积小、加载快封面搜索功能也能自动抓取。做完这一步你的游戏库从能跑升级到稳换机器、升级系统后依然省心。下一步打开 Web UI 亲手添加并验证现在就去实践打开 https://localhost:47990 → 进入「应用」→ 点「添加」→ 按最小配置填入一个 Steam 游戏 → 保存后用 Moonlight 点击启动确认能流畅进入游戏画面再给另一个应用配上分辨率预备命令比较串流前后的显示效果。全程无需改一行配置文件JSON 会自动同步。想深入研究的读者可继续翻阅项目内的这些一手资料官方配置文档 docs/configuration.md、应用示例合集 docs/app_examples.md、Web UI 前端源码 src_assets/common/assets/web/apps.html。做完这一步你已经亲手完成了一个完整的串流应用配置闭环从添加、优化到排障的整套流程都过了手。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考