Sunshine 应用添加实战指南从桌面到游戏启动的配置示例与命令体系详解【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine本文档是给 Moonlight 客户端用户添加可串流应用Application的配置实战指南围绕 Sunshine 仓库中 docs/app_examples.md 的核心示例展开。读者在 Web UI 的 Applications应用管理页添加条目时将掌握桌面直连、Steam / Epic 启动器 URI 与二进制三种启动方式以及针对不同桌面环境与显卡的分辨率切换 Prep Command预备命令写法并理解各字段在 src/process.cpp 中的实际执行语义。目录理解应用配置的核心概念通用示例桌面与 Steam Big Picture游戏启动器示例Epic 与 Steam 游戏Prep Commands分辨率与刷新率切换附加考虑事项总结与进一步阅读一、理解应用配置的核心概念1.1 为什么要「逐应用」配置并非所有应用都以相同的方式启动桌面环境、Steam 自带自更新进程、Epic 启动器需要通过 URL Scheme 唤醒游戏、有的游戏二进制必须带工作目录运行。Sunshine 因此在应用条目中提供了若干灵活字段从而让主机的输出行为分辨率、刷新率、HDR与「应用是否仍在运行」的判定完全可控。1.2 需要理解的关键字段在 src/confighttp.cpp 的saveApp接口注释中Sunshine 完整定义了应用条目的 JSON 结构字段说明如下字段类型含义name字符串应用显示名Application Nameoutput字符串日志输出文件路径Log Output Pathcmd字符串应用启动命令Command。为空表示启动桌面Desktopindex整数保存位置索引-1表示新建更新已有应用时传入其当前索引exclude-global-prep-cmd布尔是否跳过 Sunshine 配置文件中global_prep_cmd定义的所有全局预备命令见 docs/configuration.md 的global_prep_cmd小节elevated布尔该应用命令是否以管理员权限启动auto-detach布尔应用启动后 5 秒内即优雅退出时是否将其视为脱离型detached命令继续串流wait-all布尔是否等待整个进程组退出而非只等待初始进程才算应用结束exit-timeout整数关闭应用时向进程组发送终止信号后等待的秒数prep-cmd数组预备命令数组每项含do启动前执行、undo应用退出后执行与可选的elevateddetached数组需要分离式启动不阻塞应用运行状态判定的命令每项为一个命令字符串image-path字符串应用图标路径必须是 png 文件可填desktop.png、steam.png等仓库内置图标working-dir字符串应用工作目录留空时默认指向目标程序所在目录1.3 默认工作目录与「空命令 桌面」的底层逻辑原文给出了两条重要约定均可在源码中得到印证Working Directory 缺省时Sunshine 默认将其设置为目标应用所在目录。在 src/process.cpp 中无论是do/undo预备命令第 224-226 行还是 detached 命令第 253-255 行、主cmd第 269-271 行都执行了同一逻辑_app.working_dir.empty() ? find_working_directory(cmd, _env) : path(_app.working_dir)。cmd留空时 Sunshine 不会启动任何进程而是进入「桌面占位」模式placebo true见 src/process.cpp此时串流目标是整个桌面应用持续「运行」直到客户端断开。此外Sunshine 还会在启动应用时向子进程注入一组SUNSHINE_*环境变量src/process.cpp包括SUNSHINE_APP_ID、SUNSHINE_APP_NAME当前应用标识SUNSHINE_CLIENT_NAME客户端名称SUNSHINE_CLIENT_WIDTH、SUNSHINE_CLIENT_HEIGHT、SUNSHINE_CLIENT_FPS、SUNSHINE_CLIENT_HDR客户端本次请求的分辨率、帧率与 HDR 开关SUNSHINE_CLIENT_GCMAP、SUNSHINE_CLIENT_AUDIO_CONFIGURATION2.0/5.1/7.1等音频配置这些环境变量是下文中所有「动态分辨率切换」命令的数据来源。二、通用示例桌面与 Steam Big Picture2.1 Desktop桌面直连当你只想把整个桌面画面串流给 Moonlight 时添加如下条目原文的code{}记号在 Web UI 中即对应相应输入框内容字段值Application NameDesktopImagedesktop.png对应的apps.json条目与仓库中预置的 src_assets/linux/assets/apps.json 完全一致应用名Desktop、无cmd图片为desktop.png。该示例文件同时给出了一个「Low Res Desktop」变体用prep-cmd在启动前把显示器切到 1920x1080、退出后还原到 1920x1200可以作为最简单的 Prep Command 参考{ name: Low Res Desktop, image-path: desktop.png, prep-cmd: [ { do: xrandr --output HDMI-1 --mode 1920x1080, undo: xrandr --output HDMI-1 --mode 1920x1200 } ] }2.2 Steam Big Picture大屏模式Steam 启动后其主进程会被自更新进程替换并退出因此必须以 detached分离式命令启动并用prep-cmd的undo负责在串流结束后关闭大屏模式。各平台字段如下平台Application NameCommand Preparations → UndoDetached CommandsFreeBSD / LinuxSteam Big Picturesetsid steam steam://close/bigpicturesetsid steam steam://open/bigpicturemacOSSteam Big Pictureopen steam://close/bigpictureopen steam://open/bigpictureWindowsSteam Big Picturesteam://close/bigpicturesteam://open/bigpicture原仓库示例 src_assets/linux/assets/apps.json 中的 Steam Big Picture 条目即采用此写法image-path为steam.png{ name: Steam Big Picture, detached: [ setsid steam steam://open/bigpicture ], prep-cmd: [ { do: , undo: setsid steam steam://close/bigpicture } ], image-path: steam.png }理解这一结构的代码语义在 src/process.cpp 中detached数组中的每条命令都会通过run_command启动后立即调用child.detach()脱离管理主进程是否存活不会影响串流会话而prep-cmd中的do启动前与undo应用退出后是同步等待执行的。值得注意do留空会被跳过if (cmd.do_cmd.empty()) continue;见 src/process.cpp这正是上面条目中do为空的原因——Steam 的开启动作交给 detached 完成。[!TIP] 本示例相关的单元测试可在 tests/unit/test_process.cpp 中查看。三、游戏启动器示例Epic 与 Steam 游戏原文强调使用启动器的 URI 方式最稳定一致因为它不依赖游戏二进制路径随商店更新而变化。3.1 Epic Game Store 游戏以《Surviving Mars》为例URI 方式字段值Application NameSurviving MarsCommandscom.epicgames.launcher://apps/d759128018124dcabb1fbee9bb28e178%3A20729b9176c241f0b617c5723e70ec2d%3AOvenbird?actionlaunchsilenttrue其中路径段:AppCatalogItemId:AppItemId冒号被编码为%3A由 Epic 启动器为每个游戏生成可在启动器中获取。Binary带工作目录字段值Application NameSurviving MarsCommandMarsEpic.exeWorking DirectoryC:\Program Files\Epic Games\SurvivingMarsBinary不带工作目录字段值Application NameSurviving MarsCommandC:\Program Files\Epic Games\SurvivingMars\MarsEpic.exe后两者对比直观演示了工作目录规则如果你不填 Working Directory就必须把 Command 写成完整可执行文件路径让 Sunshine 依据「默认工作目录 程序所在目录」的规则见上文 src/process.cpp自行推断若提供了 Working Directory则 Command 只需写可执行文件名。3.2 Steam 游戏以《Surviving Mars》Steam AppID 464920 为例URI 方式推荐平台Detached CommandsFreeBSD / Linuxsetsid steam steam://rungameid/464920macOSopen steam://rungameid/464920Windowssteam://rungameid/464920所有平台只需填 Detached Commands无需 prep 命令——和 Steam Big Picture 一样因为 Steam 主进程自更新的特性要求分离式启动。Binary带工作目录字段FreeBSD / Linux / macOS 值Windows 值CommandMarsSteamMarsSteam.exeWorking Directory$(HOME)/.steam/steam/SteamApps/common/Surviving MarsC:\Program Files (x86)\Steam\steamapps\common\Surviving Mars[!NOTE] Linux/macOS 的 Steam 默认库位于$(HOME)/.steam/steam/SteamApps对应 Windows 的C:\Program Files (x86)\Steam\steamapps若你安装了额外的 Steam 库请把路径替换为实际安装目录。原文保留了路径中Survivng Mars的拼写配置时以你机器上的实际目录名为准。Binary不带工作目录Command 直接写完整可执行文件路径平台CommandFreeBSD / Linux / macOS$(HOME)/.steam/steam/SteamApps/common/Surviving Mars/MarsSteamWindowsC:\Program Files (x86)\Steam\steamapps\common\Surviving Mars\MarsSteam.exe四、Prep Commands分辨率与刷新率切换游戏/桌面运行时往往需要把显示器临时切换为客户端请求的分辨率与帧率尤其是不同步的物理显示与无线串流场景串流结束后再还原。Sunshine 为此在每个应用条目中提供了prep-cmd数组并在运行时通过SUNSHINE_CLIENT_WIDTH / HEIGHT / FPS / HDR环境变量见 src/process.cpp把客户端请求值传给命令。do命令在应用启动前同步执行若失败则中止本次启动返回非零退出码会令proc_t::start()返回 -1见 src/process.cppundo命令在会话结束后执行用于恢复物理显示器。以下按平台与显示服务器整理原文给出的完整命令表。4.1 LinuxX11通用及 GNOME/X11Prep StepCommandDosh -c xrandr --output HDMI-1 --mode ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --rate ${SUNSHINE_CLIENT_FPS}Undoxrandr --output HDMI-1 --mode 3840x2160 --rate 120[!TIP] 上述命令仅在 xrandr 模式已存在时有效。macOS 与 iOS 客户端使用非标准分辨率通常需要先动态创建新模式。可以将do换成调用自定义脚本bash -c ${HOME}/scripts/set-custom-res.sh \${SUNSHINE_CLIENT_WIDTH}\ \${SUNSHINE_CLIENT_HEIGHT}\ \${SUNSHINE_CLIENT_FPS}\脚本set-custom-res.sh内容如下可存至~/scripts/并chmod x#!/bin/bash set -e # Get params and set any defaults width${1:-1920} height${2:-1080} refresh_rate${3:-60} # You may need to adjust the scaling differently so the UI/text isnt too small / big scale${4:-0.55} # Get the name of the active display display_output$(xrandr | grep connected | awk { print $1 }) # Get the modeline info from the 2nd row in the cvt output modeline$(cvt ${width} ${height} ${refresh_rate} | awk FNR 2) xrandr_mode_str${modeline//Modeline \*\ /} mode_alias${width}x${height} echo xrandr setting new mode ${mode_alias} ${xrandr_mode_str} xrandr --newmode ${mode_alias} ${xrandr_mode_str} xrandr --addmode ${display_output} ${mode_alias} # Reset scaling xrandr --output ${display_output} --scale 1 # Apply new xrandr mode xrandr --output ${display_output} --primary --mode ${mode_alias} --pos 0x0 --rotate normal --scale ${scale} # Optional reset your wallpaper to fit to new resolution # xwallpaper --zoom /path/to/wallpaper.png该脚本用cvt生成目标分辨率的 modeline、创建新模式后施加到当前活动显示器并通过--scale调节 UI 缩放比例。需要恢复壁纸时可取消最后一行xwallpaper的注释。Waylandwlroots 系合成器如 HyprlandPrep StepCommandDosh -c wlr-xrandr --output HDMI-1 --mode \${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}${SUNSHINE_CLIENT_FPS}Hz\Undowlr-xrandr --output HDMI-1 --mode 3840x2160120Hz[!TIP]wlr-xrandr仅适用于 wlroots 系合成器Hyprland、Sway 等其余 Wayland 合成器请使用下列专门方案。GNOMEWaylandPrep StepCommandDosh -c displayconfig-mutter set --connector HDMI-1 --resolution ${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} --refresh-rate ${SUNSHINE_CLIENT_FPS} --hdr ${SUNSHINE_CLIENT_HDR}Undodisplayconfig-mutter set --connector HDMI-1 --resolution 3840x2160 --refresh-rate 120 --hdr false需要先安装displayconfig-mutter工具相关安装说明请查看其上游仓库。可替代工具包括gnome-randr-rust与gnome-randr.py但两者均已停止维护且不支持较新 Mutter 的 HDR、VRR 特性故不推荐。HDR 支持自 GNOME 48 起提供。可用displayconfig-mutter list检查显示器是否支持 HDR若不支持请将do与undo命令中的--hdr参数一并移除。KDE PlasmaWayland 与 X11Prep StepCommandDosh -c kscreen-doctor output.HDMI-A-1.mode.${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT}${SUNSHINE_CLIENT_FPS}Undokscreen-doctor output.HDMI-A-1.mode.3840x2160120[!CAUTION] X11 与 Wayland 下的显示器名称可能不同例如同一台显示器在 X11 叫HDMI-A-0在 Wayland 下可能叫HDMI-A-1务必根据当前会话类型使用正确的名称。[!TIP] 用kscreen-doctor -o可列出所有可用显示器及其支持的属性然后将命令中的HDMI-A-1替换为你要用于 Moonlight 的显示器名。你也可以硬编码显示器模式编号如kscreen-doctor output.HDMI-A1.mode.0或用上面的do命令动态采用 Moonlight 客户端请求的分辨率该值有一定概率不被物理显示器支持。NVIDIAPrep StepCommandDosh -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 }\Undonvidia-settings -a CurrentMetaModeHDMI-1: nvidia-auto-select { ViewPortIn3840x2160, ViewPortOut3840x216000 }4.2 macOS使用displayplacer工具切换分辨率该工具由 jakehilborn 维护需按其在 GitHub 仓库的说明安装。Prep StepCommandDosh -c displayplacer \id:screenId res:${SUNSHINE_CLIENT_WIDTH}x${SUNSHINE_CLIENT_HEIGHT} hz:${SUNSHINE_CLIENT_FPS} scaling:on origin:(0,0) degree:0\Undodisplayplacer id:screenId res:3840x2160 hz:120 scaling:on origin:(0,0) degree:0命令中的screenId请替换为运行displayplacer list输出的目标显示器 ID。4.3 WindowsSunshine 在 Windows 上内置了分辨率/刷新率切换能力相关实现见 src/platform/windows/display_base.cpp、display_ram.cpp 等文件并非必须使用第三方工具若希望用外部工具可参考 QRes从 SourceForge 下载Prep StepCommandDocmd /C FullPath\qres.exe /x:%SUNSHINE_CLIENT_WIDTH% /y:%SUNSHINE_CLIENT_HEIGHT% /r:%SUNSHINE_CLIENT_FPS%UndoFullPath\qres.exe /x:3840 /y:2160 /r:120注意 Windows 下环境变量引用采用%VAR%语法而非 Unix 的${VAR}且需把FullPath\qres.exe替换为 QRes 的实际安装路径。五、附加考虑事项5.1 LinuxFlatpak 环境[!CAUTION] Flatpak 包运行在沙箱中默认无法访问宿主机。因此Sunshine 的 Flatpak 版本要求所有命令以flatpak-spawn --host作为前缀例如flatpak-spawn --host xrandr ...否则命令无法操作宿主的显示输出。5.2 Windows提升命令权限Elevating Commands如果将 Sunshine 作为 Windows 服务运行默认方式应用可能需要在无 UAC 弹窗的情况下以管理员权限执行命令。可在 Web UI 中勾选相应选项或在apps.json中为命令添加elevated: true。该选项同时适用于普通cmd/prep-cmd进程会以当前登录用户身份被提升启动对应 src/platform/windows/misc.cpp 中retrieve_users_token的令牌获取逻辑。完整示例{ name: Game With AntiCheat that Requires Admin, output: , cmd: ping 127.0.0.1, exclude-global-prep-cmd: false, elevated: true, prep-cmd: [ { do: powershell.exe -command \Start-Streaming\, undo: powershell.exe -command \Stop-Streaming\, elevated: false } ], image-path: }运行时elevated在 src/confighttp.cpp 中被从旧版本常用的字符串true/false规范化为真正的布尔值同一处理还覆盖exclude-global-prep-cmd、auto-detach、wait-all与整数型的exit-timeout随后在配置解析时被填充为 src/config.h 定义的prep_cmd_t{ do_cmd, undo_cmd, elevated }并最终传入platf::run_command(elevated, ...)执行。5.3 相关代码路径速查若想从源码层面验证以上行为可按下列路径深入应用条目的 JSON 完整格式与保存逻辑src/confighttp.cppsaveAppprep-cmd结构体定义do_cmd/undo_cmd/elevatedsrc/config.h应用启动时序prepdo→ detached → 主cmd→ 应用退出后反向执行 prepundosrc/process.cpp 与 src/process.cppterminate客户端请求注入的环境变量SUNSHINE_CLIENT_*src/process.cppauto-detach的 5 秒优雅退出判定src/process.cpp仓库内置的应用示例文件src_assets/linux/assets/apps.json其它平台内置apps.jsonsrc_assets/macos/assets/apps.json、src_assets/windows/assets/apps.json六、总结与进一步阅读本文从「为什么要逐应用配置」出发介绍了 Sunshine 应用条目的全部核心字段逐一演示了桌面、Steam Big Picture、Epic 与 Steam 游戏在 URI / 二进制两种启动方式下的完整填法并系统整理了各桌面环境与显卡在 X11、Wayland、macOS、Windows 下的分辨率切换 Prep Command。需要特别记住的三条规则是工作目录缺省指向程序所在目录、cmd留空即为桌面直连、Steam 系必须走 detached 启动。结合源码可见这些字段都对应 src/process.cpp 中明确的执行分支理解后可大幅提升排查启动异常的效率。关于 Sunshine 全部配置项含global_prep_cmd等的完整说明见 docs/configuration.md本文中命令用到的SUNSHINE_CLIENT_*环境变量的注入逻辑可回溯 src/process.cpp。若需要更多第三方应用案例可继续阅读 docs/awesome_sunshine.md 社区资源清单。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考