从零添加你的第一个游戏Sunshine 应用管理完整指南【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine你打开 Sunshine 的 Web 界面满怀期待地准备串流昨晚刚买的 3A 大作却发现Applications页面里只有孤零零的 Desktop 和 Steam Big Picture 两个预设项。别慌这几乎是每个 Sunshine 新手都会遇到的第一道坎——游戏库管理。Sunshine 作为一套自托管的游戏流媒体服务器它的灵魂不在编码器而在那个决定按下串流键后到底运行什么的应用配置系统。搞清楚它你就能把任意平台、任意启动方式的游戏都变成一键串流的入口。这篇指南会带你从零搭建自己的游戏库顺便把背后的机制也讲透。先看结果你最终会得到什么配置完成后你的Applications页面会长这样每个游戏一张卡片带图标、启动路径、编辑和删除按钮点一下就能从 Moonlight 客户端远程启动。注意页面顶部那句提示Applications are refreshed only when Client is restarted——应用列表只在客户端重启时刷新所以改完配置后记得在 Moonlight 里刷新一下否则看不到新游戏。原理速览一个 JSON 文件驱动的应用引擎Sunshine 的应用管理远比你想的简单。它没有数据库没有复杂的服务注册核心就是一个apps.json文件。整个链路是这样的这个文件默认位于 Sunshine 的配置目录下通常与sunshine.conf同级文件名就叫apps.json对应源码里的APPS_JSON_PATH常量。它是个标准的 JSON 数组每个元素描述一个应用叫什么名字、运行什么命令、要不要提前做点什么、图标在哪。你完全可以在 Web UI 里图形化编辑也可以直接手写这个文件——两种方式殊途同归。理解了这个机制你就明白为什么说Sunshine 应用管理 管理一个 JSON 数组。分步实操添加第一个游戏我们以最常见的 Steam 游戏为例走一遍完整流程。Steam 游戏推荐用URI 方式启动也就是steam://rungameid/游戏ID因为它绕开了 Steam 自身的更新进程和路径问题最稳定。第一步找到游戏 ID在 Steam 商店页面或游戏库中右键游戏属性或者直接看商店 URL——https://store.steampowered.com/app/1091500/Cyberpunk_2077/里的1091500就是游戏 ID。记下它。第二步在 Web UI 中添加应用打开 Sunshine Web UI默认https://localhost:47990进入Applications页面点击右下角蓝色的Add New按钮填写表单Application Name填游戏名比如 Cyberpunk 2077Image可选填应用图标文件名也可以不填留空会显示默认占位图Detached Commands填入steam://rungameid/1091500保存第三步理解分离命令而非主命令这里有个新手最容易踩的坑为什么填的是 Detached 而不是 Command因为 Steam 启动游戏时会先自更新然后由新进程接管最初那个进程会退出。如果填在主命令Command里Sunshine 检测到目标进程退出就会立刻结束串流会话——游戏刚开就被掐断。分离命令detached的意思是Sunshine 只管把这个命令发射出去不追踪它的生命周期串流会话继续维持。这就是为什么所有 Steam 类游戏都推荐 detached 方式。第四步直连二进制游戏的方式如果你有独立运行的游戏比如 Epic 商店下载的或直接解压的绿色版就用主命令方式{ name: Surviving Mars, cmd: MarsEpic.exe, working-dir: C:\\Program Files\\Epic Games\\SurvivingMars, image-path: surviving-mars.png }上面这段配置里cmd是主执行程序Sunshine 会持续追踪它的进程状态进程结束串流就结束working-dir指定工作目录——不填的话Sunshine 默认取命令所在目录所以要么写全路径要么保证工作目录正确image-path是显示在 Web UI 和应用列表里的图标 小结URI 启动Steam/Epic填 detached直接执行程序填 cmd。前者发射不管后者跟踪到结束。参数速查表一张表看懂所有字段以下字段在 Web UI 里都能对应找到直接写 JSON 时也通用字段名类型说明示例namestring应用显示名称必填Cyberpunk 2077cmdstring/array主执行命令进程退出即结束串流game.exedetachedarray分离命令发射后不追踪[steam://rungameid/1091500]prep-cmdarray预备命令启动前执行/结束后撤销[{do: ..., undo: ...}]working-dirstring工作目录默认取命令所在目录C:\\Games\\Cyberpunkimage-pathstring应用图标路径cyberpunk.pngelevatedbool是否以管理员权限运行Windowstrueauto-detachbool启动后5秒内退出则自动转为分离模式truewait-allbool是否等待所有子进程退出falseexit-timeoutint收到退出信号后强制结束的等待秒数3exclude-global-prep-cmdbool是否跳过全局预备命令true全局预备命令是什么在 Configuration 页面的Command Preparations里配置会对所有应用生效。某个应用想跳过它就设置exclude-global-prep-cmd: true。进阶技巧预备命令与环境变量让串流更聪明预备命令prep-cmd是 Sunshine 应用管理里最有价值的功能在游戏启动前执行do在串流结束后执行undo。最典型的用途是动态切换分辨率。动态分辨率调整Windows不同客户端设备分辨率不同你在 4K 电视和 1080p 笔记本之间切换时总不能每次手动改系统分辨率。用预备命令加环境变量就能全自动{ name: Cyberpunk 2077, cmd: game.exe, prep-cmd: [ { do: cmd /C \C:\\Tools\\QRes.exe /X:%SUNSHINE_CLIENT_WIDTH% /Y:%SUNSHINE_CLIENT_HEIGHT% /R:%SUNSHINE_CLIENT_FPS%\, undo: C:\\Tools\\QRes.exe /X:1920 /Y:1080 /R:60 } ] }do里的%SUNSHINE_CLIENT_WIDTH%、%SUNSHINE_CLIENT_HEIGHT%、%SUNSHINE_CLIENT_FPS%是 Sunshine 注入的环境变量取的是当前发起串流的客户端请求的分辨率和帧率undo在会话结束后把分辨率恢复成你平时使用的 1920x108060别忘了写 undo否则串流结束你的显示器分辨率就回不来了Linux X11 环境的分辨率设置Linux 下思路一样换成xrandr即可{ 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 } ] }注意 Linux 下环境变量要用${}展开并用sh -c包裹而 Windows 用%VAR%别混用。常用环境变量一览这些变量来自源码process.cpp中的进程环境注入逻辑凡是通过 Sunshine 启动的进程都能读到环境变量描述示例值SUNSHINE_APP_NAME当前应用名称Cyberpunk 2077SUNSHINE_APP_ID当前应用在列表中的序号3SUNSHINE_CLIENT_WIDTH客户端请求的宽度1920SUNSHINE_CLIENT_HEIGHT客户端请求的高度1080SUNSHINE_CLIENT_FPS客户端请求的帧率60SUNSHINE_CLIENT_HDR客户端是否启用 HDRtrue/false在预备命令脚本里自由组合它们你甚至可以按客户端分辨率自动决定启动哪个版本的配置文件。 小结prep-cmd 的do/undo是对称的一对只写do不写undo等于给系统留下了一个脏状态。避坑指南三个高频故障的排查思路故障一游戏启动后串流立刻结束症状是你刚在 Moonlight 上点启动画面闪一下就退回主界面。十有八九是命令方式选错了——Steam/Epic 这类带自更新进程的游戏填进了cmd而非detached。自查顺序改用detached方式启动或者设置auto-detach: true让 Sunshine 在检测到启动后 5 秒内进程退出时自动转为分离模式确认命令本身能独立运行先在主机上手动执行一次故障二游戏启动了但手柄/键鼠完全没反应检查方向要分平台LinuxSunshine 运行用户必须加入input组否则无法创建虚拟输入设备。执行sudo usermod -a -G input 你的用户名后注销重登Windows确认虚拟手柄驱动已安装串流期间拔插手柄会中断虚拟设备绑定先重插再重连串流故障三串流分辨率跟客户端不匹配画面拉伸变形或黑边多半是没做动态分辨率切换。按上面的 prep-cmd 方案配置并检查两点预备命令里的变量名拼写是否正确、目标显示器是否支持该分辨率模式不支持时 xrandr 会直接报错注意查看 Sunshine 日志。最佳实践清单把游戏库管得井井有条☐能走 URI 就走 URISteam、Epic 等平台游戏一律用 URI 启动比定位 exe 稳定得多☐Windows 游戏路径用双反斜杠C:\\Program Files\\...单个反斜杠会被 JSON 转义吃掉☐每个应用都配图标用image-path指定 PNG 图标库一多你就知道这多重要☐prep-cmd 务必成对写do的同时写undo退出后恢复现场☐新应用添加后重启客户端Moonlight 端刷新应用列表再测试避免看不到新游戏的假故障☐改完配置先测命令行把cmd/detached里的命令拿到终端里手动跑一遍确认能启动再填进配置能省一半排查时间☐定期备份 apps.json重装系统或迁移主机时拷走这一个文件就带走了整个游戏库延伸阅读往深处挖一挖想彻底掌握应用管理的实现细节可以从这些入口继续官方示例库docs/app_examples.md包含 Steam、Epic、各类模拟器、甚至自定义脚本的跨平台配置案例配置字段完整文档docs/configuration.md所有配置项的权威说明应用解析与执行源码src/config.cppJSON 解析与字段读取和 src/process.cpp进程启动、环境变量注入、分离命令逻辑Web 界面源码src_assets/common/assets/web/apps.html看完你就知道 UI 上每个字段背后对应哪个 JSON 键现在打开你的 Sunshine Web UIAdd New 一个 Steam 游戏试试——记得先看游戏 ID填进 Detached Commands保存然后回 Moonlight 刷新。等串流画面里游戏顺利跑起来的那一刻你会觉得这十分钟的配置完全值得。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从零添加你的第一个游戏：Sunshine 应用管理完整指南
从零添加你的第一个游戏Sunshine 应用管理完整指南【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine你打开 Sunshine 的 Web 界面满怀期待地准备串流昨晚刚买的 3A 大作却发现Applications页面里只有孤零零的 Desktop 和 Steam Big Picture 两个预设项。别慌这几乎是每个 Sunshine 新手都会遇到的第一道坎——游戏库管理。Sunshine 作为一套自托管的游戏流媒体服务器它的灵魂不在编码器而在那个决定按下串流键后到底运行什么的应用配置系统。搞清楚它你就能把任意平台、任意启动方式的游戏都变成一键串流的入口。这篇指南会带你从零搭建自己的游戏库顺便把背后的机制也讲透。先看结果你最终会得到什么配置完成后你的Applications页面会长这样每个游戏一张卡片带图标、启动路径、编辑和删除按钮点一下就能从 Moonlight 客户端远程启动。注意页面顶部那句提示Applications are refreshed only when Client is restarted——应用列表只在客户端重启时刷新所以改完配置后记得在 Moonlight 里刷新一下否则看不到新游戏。原理速览一个 JSON 文件驱动的应用引擎Sunshine 的应用管理远比你想的简单。它没有数据库没有复杂的服务注册核心就是一个apps.json文件。整个链路是这样的这个文件默认位于 Sunshine 的配置目录下通常与sunshine.conf同级文件名就叫apps.json对应源码里的APPS_JSON_PATH常量。它是个标准的 JSON 数组每个元素描述一个应用叫什么名字、运行什么命令、要不要提前做点什么、图标在哪。你完全可以在 Web UI 里图形化编辑也可以直接手写这个文件——两种方式殊途同归。理解了这个机制你就明白为什么说Sunshine 应用管理 管理一个 JSON 数组。分步实操添加第一个游戏我们以最常见的 Steam 游戏为例走一遍完整流程。Steam 游戏推荐用URI 方式启动也就是steam://rungameid/游戏ID因为它绕开了 Steam 自身的更新进程和路径问题最稳定。第一步找到游戏 ID在 Steam 商店页面或游戏库中右键游戏属性或者直接看商店 URL——https://store.steampowered.com/app/1091500/Cyberpunk_2077/里的1091500就是游戏 ID。记下它。第二步在 Web UI 中添加应用打开 Sunshine Web UI默认https://localhost:47990进入Applications页面点击右下角蓝色的Add New按钮填写表单Application Name填游戏名比如 Cyberpunk 2077Image可选填应用图标文件名也可以不填留空会显示默认占位图Detached Commands填入steam://rungameid/1091500保存第三步理解分离命令而非主命令这里有个新手最容易踩的坑为什么填的是 Detached 而不是 Command因为 Steam 启动游戏时会先自更新然后由新进程接管最初那个进程会退出。如果填在主命令Command里Sunshine 检测到目标进程退出就会立刻结束串流会话——游戏刚开就被掐断。分离命令detached的意思是Sunshine 只管把这个命令发射出去不追踪它的生命周期串流会话继续维持。这就是为什么所有 Steam 类游戏都推荐 detached 方式。第四步直连二进制游戏的方式如果你有独立运行的游戏比如 Epic 商店下载的或直接解压的绿色版就用主命令方式{ name: Surviving Mars, cmd: MarsEpic.exe, working-dir: C:\\Program Files\\Epic Games\\SurvivingMars, image-path: surviving-mars.png }上面这段配置里cmd是主执行程序Sunshine 会持续追踪它的进程状态进程结束串流就结束working-dir指定工作目录——不填的话Sunshine 默认取命令所在目录所以要么写全路径要么保证工作目录正确image-path是显示在 Web UI 和应用列表里的图标 小结URI 启动Steam/Epic填 detached直接执行程序填 cmd。前者发射不管后者跟踪到结束。参数速查表一张表看懂所有字段以下字段在 Web UI 里都能对应找到直接写 JSON 时也通用字段名类型说明示例namestring应用显示名称必填Cyberpunk 2077cmdstring/array主执行命令进程退出即结束串流game.exedetachedarray分离命令发射后不追踪[steam://rungameid/1091500]prep-cmdarray预备命令启动前执行/结束后撤销[{do: ..., undo: ...}]working-dirstring工作目录默认取命令所在目录C:\\Games\\Cyberpunkimage-pathstring应用图标路径cyberpunk.pngelevatedbool是否以管理员权限运行Windowstrueauto-detachbool启动后5秒内退出则自动转为分离模式truewait-allbool是否等待所有子进程退出falseexit-timeoutint收到退出信号后强制结束的等待秒数3exclude-global-prep-cmdbool是否跳过全局预备命令true全局预备命令是什么在 Configuration 页面的Command Preparations里配置会对所有应用生效。某个应用想跳过它就设置exclude-global-prep-cmd: true。进阶技巧预备命令与环境变量让串流更聪明预备命令prep-cmd是 Sunshine 应用管理里最有价值的功能在游戏启动前执行do在串流结束后执行undo。最典型的用途是动态切换分辨率。动态分辨率调整Windows不同客户端设备分辨率不同你在 4K 电视和 1080p 笔记本之间切换时总不能每次手动改系统分辨率。用预备命令加环境变量就能全自动{ name: Cyberpunk 2077, cmd: game.exe, prep-cmd: [ { do: cmd /C \C:\\Tools\\QRes.exe /X:%SUNSHINE_CLIENT_WIDTH% /Y:%SUNSHINE_CLIENT_HEIGHT% /R:%SUNSHINE_CLIENT_FPS%\, undo: C:\\Tools\\QRes.exe /X:1920 /Y:1080 /R:60 } ] }do里的%SUNSHINE_CLIENT_WIDTH%、%SUNSHINE_CLIENT_HEIGHT%、%SUNSHINE_CLIENT_FPS%是 Sunshine 注入的环境变量取的是当前发起串流的客户端请求的分辨率和帧率undo在会话结束后把分辨率恢复成你平时使用的 1920x108060别忘了写 undo否则串流结束你的显示器分辨率就回不来了Linux X11 环境的分辨率设置Linux 下思路一样换成xrandr即可{ 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 } ] }注意 Linux 下环境变量要用${}展开并用sh -c包裹而 Windows 用%VAR%别混用。常用环境变量一览这些变量来自源码process.cpp中的进程环境注入逻辑凡是通过 Sunshine 启动的进程都能读到环境变量描述示例值SUNSHINE_APP_NAME当前应用名称Cyberpunk 2077SUNSHINE_APP_ID当前应用在列表中的序号3SUNSHINE_CLIENT_WIDTH客户端请求的宽度1920SUNSHINE_CLIENT_HEIGHT客户端请求的高度1080SUNSHINE_CLIENT_FPS客户端请求的帧率60SUNSHINE_CLIENT_HDR客户端是否启用 HDRtrue/false在预备命令脚本里自由组合它们你甚至可以按客户端分辨率自动决定启动哪个版本的配置文件。 小结prep-cmd 的do/undo是对称的一对只写do不写undo等于给系统留下了一个脏状态。避坑指南三个高频故障的排查思路故障一游戏启动后串流立刻结束症状是你刚在 Moonlight 上点启动画面闪一下就退回主界面。十有八九是命令方式选错了——Steam/Epic 这类带自更新进程的游戏填进了cmd而非detached。自查顺序改用detached方式启动或者设置auto-detach: true让 Sunshine 在检测到启动后 5 秒内进程退出时自动转为分离模式确认命令本身能独立运行先在主机上手动执行一次故障二游戏启动了但手柄/键鼠完全没反应检查方向要分平台LinuxSunshine 运行用户必须加入input组否则无法创建虚拟输入设备。执行sudo usermod -a -G input 你的用户名后注销重登Windows确认虚拟手柄驱动已安装串流期间拔插手柄会中断虚拟设备绑定先重插再重连串流故障三串流分辨率跟客户端不匹配画面拉伸变形或黑边多半是没做动态分辨率切换。按上面的 prep-cmd 方案配置并检查两点预备命令里的变量名拼写是否正确、目标显示器是否支持该分辨率模式不支持时 xrandr 会直接报错注意查看 Sunshine 日志。最佳实践清单把游戏库管得井井有条☐能走 URI 就走 URISteam、Epic 等平台游戏一律用 URI 启动比定位 exe 稳定得多☐Windows 游戏路径用双反斜杠C:\\Program Files\\...单个反斜杠会被 JSON 转义吃掉☐每个应用都配图标用image-path指定 PNG 图标库一多你就知道这多重要☐prep-cmd 务必成对写do的同时写undo退出后恢复现场☐新应用添加后重启客户端Moonlight 端刷新应用列表再测试避免看不到新游戏的假故障☐改完配置先测命令行把cmd/detached里的命令拿到终端里手动跑一遍确认能启动再填进配置能省一半排查时间☐定期备份 apps.json重装系统或迁移主机时拷走这一个文件就带走了整个游戏库延伸阅读往深处挖一挖想彻底掌握应用管理的实现细节可以从这些入口继续官方示例库docs/app_examples.md包含 Steam、Epic、各类模拟器、甚至自定义脚本的跨平台配置案例配置字段完整文档docs/configuration.md所有配置项的权威说明应用解析与执行源码src/config.cppJSON 解析与字段读取和 src/process.cpp进程启动、环境变量注入、分离命令逻辑Web 界面源码src_assets/common/assets/web/apps.html看完你就知道 UI 上每个字段背后对应哪个 JSON 键现在打开你的 Sunshine Web UIAdd New 一个 Steam 游戏试试——记得先看游戏 ID填进 Detached Commands保存然后回 Moonlight 刷新。等串流画面里游戏顺利跑起来的那一刻你会觉得这十分钟的配置完全值得。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考