Foundation Sunshine 配置完全指南：配置文件、全量参数详解与源码级解析
Foundation Sunshine 配置完全指南：配置文件、全量参数详解与源码级解析
本指南以 Foundation Sunshine 仓库中的 docs/configuration.md 为骨架，完整覆盖 Sunshine（Moonlight 自托管游戏串流主机）的配置文件定位、命令行覆盖方式，以及 General / Input / Audio-Video / Network / Config Files / Advanced 六大分组和 NVENC、QuickSync、AMF、VideoToolbox、Software 五类编码器下的全部可配置项：默认值、取值范围、可选枚举与实战示例一应俱全。读完本文，你将能够手写一份可运行的
sunshine.conf，理解每个参数在源码中的解析与校验路径，并能在多显卡、多显示器、HDR、虚拟显示设备（VDD）与音频回环等复杂场景下精准调参。
一、配置文件位置与启动方式
Sunshine 对大多数用户可直接使用默认配置工作，但部分场景（多显示器、HDR、特殊输入映射、编码器调优）需要进一步定制。配置文件的默认位置因操作系统而异：
| OS | 配置文件默认目录 |
|---|---|
| Docker | /config |
| Linux | ~/.config/sunshine |
| macOS | ~/.config/sunshine |
| Windows | %ProgramFiles%\Sunshine\config |
如果你希望把配置放在其他位置，只需在启动 Sunshine 时把完整配置文件路径作为第一个参数传入：
sunshine ~/sunshine_config.conf
apps.json（应用列表）的默认位置与配置文件相同；如需自定义，可通过配置文件中的 file_apps 项修改。
源码佐证：在 src/config.cpp 的 config::parse(int argc, char *argv<a href="https://link.gitcode.com/i/b6e1e171d22f0d8d304ab75a5937f12e" target="_blank">])（[src/config.cpp#L1705-L1745）中，命令行参数按以下规则解析：
- 首个不带
-/=的参数被赋给sunshine.config_file（第 1745 行），即自定义配置文件路径； - 形如
name=value的参数会解析成临时变量cmd_vars，随后覆盖配置文件中的同名项（src/config.cpp#L1780-L1782）； - 若配置文件不存在，Sunshine 会自动创建一个空文件（src/config.cpp#L1772-L1775），再读取、合并命令行变量并应用。
因此命令行覆盖的优先级高于配置文件内容，可用于临时切换端口、日志级别等而无需改动磁盘上的配置。
虽然官方推荐使用 Web UI（https://localhost:47990/config/）进行配置，但手动编辑 sunshine.conf 同样可行，下文所有示例均可直接写入配置文件。注意：配置文件中的大多数项与 Web UI 保存结果一一对应，个别项（如 keybindings、widget_token）仅在配置文件中可设。
二、General（通用设置）
2.1 locale — 界面语言
- 描述：Sunshine Web UI 使用的语言。
- 默认：
en - 示例：
locale = en - 可选值：
bg（保加利亚语）、cs（捷克语）、de（德语）、en（英语）、en_GB（英式英语）、en_US（美式英语）、es（西班牙语）、fr（法语）、it（意大利语）、ja（日语）、pt（葡萄牙语）、ru（俄语）、sv（瑞典语）、tr（土耳其语）、zh（简体中文）、zh_TW（繁体中文）。
源码佐证：这些取值在 src/config.cpp#L1627-L1644 中通过 string_restricted_f 白名单校验，非法值会被拒绝并回退默认。
2.2 sunshine_name — 客户端显示名称
- 描述：Moonlight 客户端中显示的主机名。
- 默认：PC 主机名（hostname）
- 示例：
sunshine_name = Sunshine
2.3 min_log_level — 日志级别
- 描述：输出到标准输出的最低日志级别。
- 默认：
info - 示例：
min_log_level = info - 可选值：
取值 含义 verbose全部日志；⚠️ 可能影响串流性能 debugdebug 及更高；⚠️ 可能影响串流性能 info信息级及以上 warning警告级及以上 error错误级及以上 fatal仅致命错误 none不输出日志
源码佐证：src/config.cpp#L1656-L1688 将字符串级别映射为 0–6 的整数（verbose=0 … none=6），同时兼容直接写数字（0~6）。排查串流问题时建议先升到 debug 观察，日常保持 info 以免影响性能。
2.4 global_prep_cmd — 全局准备命令
- 描述：在所有应用启动前/后执行的命令列表。任一 prep 命令失败，应用启动将被中止。
- 默认：
[] - 示例：
每个条目包含global_prep_cmd = [{"do":"nircmd.exe setdisplay 1280 720 32 144","undo":"nircmd.exe setdisplay 2560 1440 32 144"}]do（启动前执行）与undo（会话结束恢复），典型用途是配合nircmd.exe在串流前临时切换分辨率/刷新率，结束后恢复。
源码佐证：src/config.h 中的 prep_cmd_t 结构体（src/config.h#L242-L248）包含 do_cmd、undo_cmd 与 elevated 字段，由 list_prep_cmd_f(vars, "global_prep_cmd", ...)（src/config.cpp#L1490）解析到 config::sunshine.prep_cmds。
2.5 notify_pre_releases — 预发布版本通知
- 描述：是否通知 Sunshine 新预发布版本。
- 默认：
disabled - 示例：
notify_pre_releases = disabled
2.6 stop_on_last_video_session — 最后一个视频会话结束时停止应用
- 描述：启用后，当所有客户端断开时，Sunshine 结束当前应用并恢复显示器设置。内部以最后一个视频会话结束为触发点，同时关闭剩余仅控制类会话。修改后需保存并应用才生效。禁用时保留原有的 Resume 行为。
- 默认：
disabled - 示例：
stop_on_last_video_session = disabled
该参数的实际运行语义可结合 docs/stop_on_last_video_session.md 中的生命周期说明理解。
2.7 widget_token — Game Bar 小组件访问令牌
- 描述：本地 Game Bar 小组件端点（
/api/widget/state、/api/widget/action）的访问令牌。这些端点仅限 loopback（回环地址）访问，并要求请求头X-Sunshine-Token与该值一致。留空时小组件端点保持关闭（返回 404）。此字段不能在 Web UI 编辑，需手动写入sunshine.conf并重启 Sunshine；启用时建议生成随机值（如 UUID）。 - 默认：
disabled - 示例：
widget_token = 5f1e9a3c-2b7d-4e6a-9c1f-8a2b3d4e5f60 - 小组件侧配置见 gamebar-widget/README.md。
三、Input（输入设置）
3.1 controller — 允许手柄输入
- 描述：是否允许客户端手柄输入。
- 默认：
enabled - 示例：
controller = enabled
3.2 gamepad — 主机模拟的手柄类型
- 描述：在主机上模拟的手柄类型。
- 默认：
auto - 示例：
gamepad = auto - 可选值：
取值 说明 ds4DualShock 4（PS4）；仅 Windows ds5DualSense（PS5）；Windows 下需要可选 DualSense 组件，组件不可用时自动回退到手柄自动选择；保存后无需重启即对新建控制器生效 switchSwitch Pro 手柄；仅 Linux x360Xbox 360；仅 Windows xoneXbox One；仅 Linux
源码佐证：src/config.cpp#L1565 通过 get_supported_gamepad_options()（src/config.cpp#L1184，内部调用 platf::supported_gamepads）动态生成可选列表，因此不同平台 UI 展示的选项不同；运行期切换由 platf::set_global_gamepad_mode 完成（src/config.cpp#L1911-L1914）。
3.3 ds4_back_as_touchpad_click — Back 键触发触摸板点击
- 描述：允许 Select/Back 输入同时触发 DS4 触摸板点击，方便在 Xinput 设备上模拟触摸板点击。
- 默认：
enabled - 示例：
ds4_back_as_touchpad_click = enabled - 提示：仅在手动设置
gamepad = ds4时生效，其他手柄模式下不使用。
3.4 motion_as_ds4 — 运动传感器模拟为 DS4
- 描述：若客户端报告手柄带有运动传感器，则在主机上将其模拟为 DS4 手柄；禁用后，运动传感器不再参与手柄类型自动选择。
- 默认：
enabled - 示例：
motion_as_ds4 = enabled - 提示：仅在
gamepad = auto时生效。
3.5 touchpad_as_ds4 — 触摸板模拟为 DS4
- 描述：若客户端报告手柄带触摸板，则在主机上模拟为 DS4 手柄；禁用后触摸板不参与自动选择。
- 默认：
enabled - 示例：
touchpad_as_ds4 = enabled - 提示：仅在
gamepad = auto时生效。
3.6 back_button_timeout — Back 键长按模拟 Home
- 描述：Back/Select 键按住超过指定毫秒数后，模拟一次 Home/Guide 键按下。
- 默认：
-1 - 示例：
back_button_timeout = 2000 - 提示：设为负数（如默认
-1）则不模拟 Home 键。
源码佐证：src/input.cpp 中 back_button_timeout 通过 task_pool.pushDelayed(...) 实现定时触发（src/input.cpp#L1593-L1618）。
3.7 keyboard — 允许键盘输入
- 默认：
enabled；示例：keyboard = enabled
3.8 key_repeat_delay — 按键重复初始延迟
- 描述：按键开始重复前的初始延迟（毫秒），控制按键重复的快慢。
- 默认：
500 - 示例：
key_repeat_delay = 500
3.9 key_repeat_frequency — 按键重复频率
- 描述：每秒按键重复次数；支持小数。
- 默认：
24.9 - 示例：
key_repeat_frequency = 24.9
3.10 always_send_scancodes — 始终发送扫描码
- 描述：发送扫描码可提升与游戏/应用的兼容性，但非美式英语键盘布局的某些客户端可能产生错误输入。若某些应用完全无法接收键盘输入可开启；若客户端按键在主机上产生错误输入则关闭。
- 默认：
enabled - 示例：
always_send_scancodes = enabled - 注意：仅 Windows 生效。
3.11 key_rightalt_to_key_win — 右 Alt 映射为 Win 键
- 描述：当 Moonlight 无法直接发送 Windows 键时，让 Sunshine 将右 Alt 视为 Windows 键。
- 默认：
disabled - 示例：
key_rightalt_to_key_win = enabled
源码佐证：src/config.cpp#L1536-L1543 显示，该选项本质上是向 input.keybindings 中追加一条映射 0xA5 -> 0x5B。
3.12 mouse — 允许鼠标输入
- 默认：
enabled；示例：mouse = enabled
3.13 high_resolution_scrolling — 高分辨率滚动
- 描述：启用后透传 Moonlight 客户端的高分辨率滚动事件；老应用滚动过快时可关闭。
- 默认：
enabled - 示例：
high_resolution_scrolling = enabled
3.14 native_pen_touch — 原生笔/触摸透传
- 描述：启用后透传客户端的原生笔/触摸事件；老应用不支持原生笔/触摸时可关闭。
- 默认：
enabled - 示例：
native_pen_touch = enabled
3.15 keybindings — 按键重映射表
- 描述：按需重映射按键（例如 Wayland 下客户端无法捕获 Win 键）。元素必须是偶数个，按“源键码, 目标键码”成对排列（键码使用 Windows 虚拟键码）。该选项不出现在 Web UI 中。
- 默认：
keybindings = [ 0x10, 0xA0, 0x11, 0xA2, 0x12, 0xA4 ] - 示例（额外把
0x4A映射到0x4B）：keybindings = [ 0x10, 0xA0, 0x11, 0xA2, 0x12, 0xA4, 0x4A, 0x4B ]
源码佐证：keybindings 由 map_int_int_f 解析（src/config.cpp#L1534），并在按键处理时于 src/input.cpp#L834-L835 查表替换键码。
四、Audio/Video（音频/视频设置）
4.1 audio_sink — 音频回环输出设备
- 描述：用于音频回环的音频输出设备名。
- 默认：Sunshine 自动选择默认音频设备。
- 各平台查找设备名的方法：
- Linux + PulseAudio：
pacmd list-sinks | grep "name:" - Linux + PipeWire：
pactl info | grep Source # 某些情况下 Source 不可用，可尝试 Sink： pactl info | grep Sink - macOS：受系统限制 Sunshine 只能访问麦克风；串流系统音频需借助 Soundflower 或 BlackHole 等虚拟声卡。
- Windows：在命令提示符或 PowerShell 中执行：
若有多个同名声卡，改用 Device ID。Windows 下留空会捕获当前默认设备，并跟随串流期间默认设备的切换；显式指定设备后，即使 Windows 默认设备变化也保持该采集端点不变。%ProgramFiles%\Sunshine\tools\audio-info.exe
- Linux + PulseAudio：
- 示例：
- Linux：
audio_sink = alsa_output.pci-0000_09_00.3.analog-stereo - macOS：
audio_sink = BlackHole 2ch - Windows：
audio_sink = Speakers (High Definition Audio Device)
- Linux：
- 注意：需要静音主机扬声器时请使用
virtual_sink，而不是依赖audio_sink本身。
4.2 virtual_sink — 虚拟音频设备
- 描述：指定虚拟音频设备（如 Steam Streaming Speakers），让 Sunshine 在静音扬声器的同时正常串流音频。
- 默认：无（n/a）
- 示例：
virtual_sink = Steam Streaming Speakers - 常见虚拟声卡方案：
- Steam Streaming Speakers（Linux、macOS、Windows）：需已安装 Steam，并启用
install_steam_audio_drivers或至少使用过一次 Steam 远程畅玩以安装驱动。 - Virtual Audio Cable（macOS、Windows）。
- Steam Streaming Speakers（Linux、macOS、Windows）：需已安装 Steam，并启用
4.3 keep_sink_default — 保持输出设备为系统默认
- 描述：Windows 下，串流期间保持所选音频输出设备为系统默认设备；若其他应用改动了默认播放设备，Sunshine 会尝试重新选中已配置（或自动选择）的 sink。禁用时，串流期间交由 Windows 自行决定默认播放设备。
- 默认：
Disabled
4.4 stream_audio — 是否串流音频
- 描述：是否串流音频；串流“无头显示器”作为第二显示器时关闭它很有用。
- 默认：
enabled - 示例：
stream_audio = disabled
4.5 microphone_redirect_backend — 麦克风重定向后端
- 描述：选择如何将 Moonlight 的麦克风 PCM 暴露给 Windows 应用：
取值 说明 vb_cable写入 VB-CABLE 渲染端点，应用从其配对端点采集 usbip_experimental直接将 PCM 注入已签名的 Virtual Device Host 麦克风 IN 端点；不经渲染-采集回环 auto先尝试 USB/IP，失败则回退 VB-CABLE disabled拒绝麦克风重定向，但保留 Moonlight 端麦克风功能设置 - 默认：
vb_cable - 示例：
microphone_redirect_backend = auto - ⚠️ USB/IP 后端为实验特性，目前使用 DualSense 复合原型 profile；仅 Windows 支持。
4.6 stream_mic — 接收客户端麦克风音频
- 描述：是否接受兼容 Moonlight 客户端的麦克风音频并重定向到配置的 Windows 麦克风后端。
- 默认：
enabled - 示例：
stream_mic = disabled
4.7 install_steam_audio_drivers — 安装 Steam 音频驱动
- 描述：安装 Steam Streaming Speakers 驱动（若已安装 Steam），以支持环绕声与主机音频静音。
- 默认：
enabled；示例：install_steam_audio_drivers = enabled - 仅 Windows 支持。
4.8 adapter_name — 选择编码 GPU
- 描述：选择要串流的显卡。
- 默认：Sunshine 自动选择默认显卡。
- 查找方法：
- Linux + VA-API：VA-API 不要求编码 GPU 与显示 GPU 相同。
受支持的最低要求是具备ls /dev/dri/renderD* # 列出所有支持 VAAPI 的设备 vainfo --display drm --device /dev/dri/renderD129 | \ grep -E "((VAProfileH264High|VAProfileHEVCMain|VAProfileHEVCMain10).*VAEntrypointEncSlice)|Driver version"VAProfileH264High : VAEntrypointEncSlice。 - Windows：
注意：混合显卡（hybrid graphics）系统上，DXGI 报告的输出连接取决于应用被配置使用哪块显卡，不能可靠反映显示器的物理连接方式。%ProgramFiles%\Sunshine\tools\dxgi-info.exe
- Linux + VA-API：VA-API 不要求编码 GPU 与显示 GPU 相同。
- 示例：
- Linux：
adapter_name = /dev/dri/renderD128 - Windows：
adapter_name = Radeon RX 580 Series
- Linux：
4.9 output_name — 选择串流显示器
- 描述：选择要串流的显示器编号。
- 默认：Sunshine 自动选择默认显示器。
- 查找方法：
- Linux：启动日志中可见显示器列表，使用括号内的
id：
例如Info: Detecting displays Info: Detected display: DVI-D-0 (id: 0) connected: false Info: Detected display: HDMI-0 (id: 1) connected: true Info: Detected display: DP-0 (id: 2) connected: true Info: Detected display: DP-1 (id: 3) connected: false Info: Detected display: DVI-D-1 (id: 4) connected: false1。 - macOS：同理使用日志中的 id：
例如Info: Detected display: Monitor-0 (id: 3) connected: true Info: Detected display: Monitor-1 (id: 2) connected: true3。 - Windows：执行
%ProgramFiles%\Sunshine\tools\dxgi-info.exe。
- Linux：启动日志中可见显示器列表，使用括号内的
- 示例：
- Linux：
output_name = 0 - macOS：
output_name = 3 - Windows：
output_name = \\.\DISPLAY1
- Linux：
4.10 显示设备（Display Device）系列：dd_* 选项（仅 Windows）
以下选项用于串流时对显示设备做强制校验与附加配置，核心由 dd_configuration_option 开关控制。
dd_configuration_option — 显示设备的强制校验与附加配置模式：
- 默认：
disabled - 示例：
dd_configuration_option = ensure_only_display - 可选值：
取值 行为 disabled不做任何附加配置（会禁用所有 dd_配置项）verify_only仅校验显示器为激活状态（强制步骤，无附加动作） ensure_active显示器未激活则激活它 ensure_primary未激活则激活，并设为主显示器 ensure_only_display未激活则激活，并关闭其他所有显示器
源码佐证：这些模式映射到 src/display_device/parsed_config.h 中的 device_prep_e 枚举（no_operation/ensure_active/ensure_primary/ensure_only_display/ensure_secondary，parsed_config.h#L27-L33），由 device_prep_from_view 完成字符串→枚举转换（src/display_device/parsed_config.cpp#L452-L464），拓扑的保存/恢复逻辑在 src/platform/windows/display_device/settings.cpp 中实现。
dd_resolution_option — 分辨率配置模式：
- 默认：
auto - 示例：
dd_resolution_option = manual - 可选值：
disabled（不附加配置）、auto（按客户端请求分辨率切换，需 Moonlight 开启“优化游戏设置”）、manual（按dd_manual_resolution指定值切换，同样需客户端开启“优化游戏设置”）。
dd_manual_resolution — 手动分辨率：
- 默认：n/a；示例：
dd_manual_resolution = 1920x1080 - 前提：
dd_resolution_option = manual。
dd_refresh_rate_option — 刷新率配置模式：
- 默认：
auto；示例：dd_refresh_rate_option = manual - 可选值：
disabled（不附加配置）、auto（按客户端请求的 FPS 切换）、manual（按dd_manual_refresh_rate指定值切换）。
dd_manual_refresh_rate — 手动刷新率：
- 默认：n/a；示例（注意应为
dd_manual_refresh_rate，原文档此处存在笔误，写成dd_manual_resolution）：dd_manual_refresh_rate = 120 dd_manual_refresh_rate = 59.95 - 前提：
dd_refresh_rate_option = manual。
dd_hdr_option — HDR 配置模式：
- 默认：
auto；示例：dd_hdr_option = disabled - 可选值：
disabled（不附加配置）、auto（若显示器支持则按客户端请求切换 HDR 状态）。
dd_wa_hdr_toggle_delay — VDD HDR 伪色缓解：
- 描述：使用虚拟显示设备（VDD）串流时，可能错误显示 HDR 颜色；Sunshine 可通过“先关 HDR、等待指定毫秒、再开 HDR”来缓解。值为
0时关闭该 workaround（默认）；0–3000毫秒区间内生效，推荐约500毫秒。除非确实遇到 HDR 问题，否则不要开启，因为它直接影响串流启动时间。 - 默认：
0；示例：dd_wa_hdr_toggle_delay = 500 - 独立于
dd_hdr_option工作。
dd_config_revert_delay — 配置回滚延迟：
- 描述：应用关闭或最后一个会话结束后、回滚显示配置前的额外等待毫秒数，主要用于应用间快速切换时更平滑的过渡。
- 默认：
3000；示例：dd_config_revert_delay = 1500
dd_config_revert_on_disconnect — 断开即回滚：
- 描述：启用后，在所有客户端断开（而非应用关闭或会话终止）时回滚显示配置，便于不关闭当前应用就回到物理使用主机。⚠️ 部分应用在显示配置变更时可能工作异常。
- 默认：
disabled；示例：dd_config_revert_on_disconnect = enabled
4.11 max_bitrate — 最大码率
- 描述：Sunshine 编码的最大码率（Kbps）。设为
0时始终使用 Moonlight 请求的码率。 - 默认：
0 - 示例：
max_bitrate = 5000
源码佐证：码率上限与 FEC 的配合在 src/video.cpp 中体现，encoder_bitrate_from_total_bitrate / encoder_bitrate_for_total_request（src/video.cpp#L225-L240）按 FEC 百分比从总码率反推编码器实际码率，cap_initial_encoder_bitrate（src/video.cpp#L244-L252）在会话开始时对初始码率做封顶。
五、Network（网络设置）
5.1 upnp — 自动端口映射
- 描述：Sunshine 是否尝试为互联网串流打开端口（UPnP）。
- 默认：
disabled；示例：upnp = enabled
5.2 address_family — 地址族
- 描述：Sunshine 使用的地址族。
- 默认：
ipv4 - 示例：
address_family = both - 可选值：
ipv4（仅 IPv4）、both（IPv4+IPv6）。
5.3 bind_address — 绑定 IP
- 描述：将 Sunshine 绑定到指定 IP。多网卡场景下用于限定监听接口；不设置时绑定所有可用接口（IPv4 为
0.0.0.0，IPv6 为::）。地址必须对系统有效且与address_family匹配；使用 IPv6 时即使address_family = both也可指定 IPv6 地址。 - 默认：空（绑定所有接口）
- 示例：IPv4
bind_address = 192.168.1.100；IPv6bind_address = 2001:db8::1；回环bind_address = 127.0.0.1
5.4 port — 端口族
- 描述：Sunshine 使用的端口族基址。修改它会像配置 UI 中显示的那样整体偏移其他端口。
- 默认：
47989 - 范围：
1029-65514 - 示例：
port = 47989
5.5 origin_web_ui_allowed — Web UI 访问来源
- 描述：允许访问 HTTPS Web UI 的远端来源范围。
- 默认：
lan - 示例：
origin_web_ui_allowed = lan - 可选值：
pc（仅本机可访问）、lan（仅局域网设备）、wan（任何人可访问）。
5.6 external_ip — 外部 IP
- 描述：未指定时 Sunshine 自动探测外部 IP。
- 默认：自动探测
- 示例：
external_ip = 123.456.789.12
5.7 lan_encryption_mode — 局域网加密模式
- 描述：局域网串流何时启用加密。⚠️ 加密可能降低串流性能，尤其性能较弱的主机/客户端。
- 默认：
0 - 可选值：
取值 行为 0不使用加密 1客户端支持时使用加密 2强制加密，拒绝未加密连接
5.8 wan_encryption_mode — 广域网加密模式
- 描述：互联网串流何时启用加密。⚠️ 同上，可能影响性能。
- 默认：
1 - 可选值：同
lan_encryption_mode（0/1/2）。
5.9 ping_timeout — 客户端数据超时
- 描述：关闭串流前等待 Moonlight 数据的毫秒数。
- 默认：
10000 - 示例：
ping_timeout = 10000
六、Config Files（文件设置）
6.1 file_apps — 应用列表文件
- 描述：应用配置文件路径，内容为可由 Moonlight 启动的应用 JSON 列表。
- 默认：
apps.json - 示例：
file_apps = apps.json
源码佐证：src/config.cpp#L1517-L1530 中，若目标路径不存在，会自动从内置资源（SUNSHINE_ASSETS_DIR "/apps.json"）复制一份。各平台内置模板见 src_assets/linux/assets/apps.json、src_assets/windows/assets/apps.json、src_assets/macos/assets/apps.json；应用条目格式示例可参考 docs/app_examples.md。
6.2 credentials_file — 用户凭据文件
- 描述：Web UI 用户凭据存储文件。
- 默认：
sunshine_state.json（注意源码中credentials_file默认取自file_state，见 src/config.cpp#L1465-L1467） - 示例：
credentials_file = sunshine_state.json
6.3 log_path — 日志文件
- 描述：Sunshine 日志存储路径。
- 默认：
sunshine.log - 示例：
log_path = sunshine.log
6.4 pkey — Web UI 与配对私钥
- 描述：Web UI 与 Moonlight 客户端配对使用的私钥。为最佳兼容性，应为 RSA-2048 私钥。⚠️ 并非所有 Moonlight 客户端支持 ECDSA 或非 2048 位 RSA。
- 默认：
credentials/cakey.pem - 示例：
pkey = /dir/pkey.pem
6.5 cert — Web UI 与配对证书
- 描述：Web UI 与 Moonlight 客户端配对使用的证书。最佳兼容性要求 RSA-2048 公钥。
- 默认：
credentials/cacert.pem - 示例：
cert = /dir/cert.pem
6.6 file_state — 状态文件
- 描述：Sunshine 当前状态存储文件。
- 默认：
sunshine_state.json - 示例：
file_state = sunshine_state.json
七、Advanced（高级设置）
7.1 fec_percentage — 前向纠错百分比
- 描述：每个视频帧中，每数据包的纠错包百分比。⚠️ 越高抗网络丢包越强，但带宽占用越高。
- 默认：
20 - 范围：
1-255 - 示例：
fec_percentage = 20
7.2 qp — 量化参数
- 描述：部分设备不支持恒定码率（CBR），此时改用 QP。⚠️ 值越大压缩越强、画质越低。
- 默认：
28 - 示例：
qp = 28
7.3 min_threads — 编码最小线程数
- 描述：用于编码的最小 CPU 线程数。⚠️ 增大该值会略微降低编码效率，但通常值得，以换取更多 CPU 核参与编码；理想值是在目标串流设置下能够稳定编码的最低值。
- 默认：
2 - 示例：
min_threads = 2
7.4 hevc_mode — HEVC 支持模式
- 描述：是否允许客户端请求 HEVC Main / HEVC Main10 流。⚠️ HEVC 编码更耗 CPU，软件编码下开启可能降低性能。
- 默认：
0 - 示例：
hevc_mode = 2 - 可选值：
取值 行为 0按编码器能力自动宣告支持 HEVC（推荐） 1不宣告支持 HEVC 2宣告支持 HEVC Main profile 3宣告支持 HEVC Main 与 Main10（HDR）
7.5 av1_mode — AV1 支持模式
- 描述：是否允许客户端请求 AV1 Main 8-bit / 10-bit 流。⚠️ AV1 编码更耗 CPU。
- 默认：
0 - 示例：
av1_mode = 2 - 可选值：
取值 行为 0按编码器能力自动宣告支持 AV1（推荐） 1不宣告支持 AV1 2宣告支持 AV1 Main 8-bit 3宣告支持 AV1 Main 8-bit 与 10-bit（HDR）
源码佐证：hevc_mode/av1_mode 在 src/config.cpp#L1203-L1204 通过 int_between_f(vars, ..., {0, 3}) 校验取值范围。
7.6 capture — 强制采集方式
- 描述：强制指定屏幕采集方法。
- 默认：自动（按上表顺序选用第一个可用方法）。
- 示例：
capture = kms - 可选值：
取值 说明 nvfbcNVIDIA Frame Buffer Capture，直接采集到 GPU 内存，通常对 NVIDIA 卡最快；不支持原生 Wayland 且不兼容 XWayland；仅 Linux wlr通过 DMA-BUF 采集 wlroots 系 Wayland 合成器；仅 Linux kms内核 DRM/KMS 采集，要求 Sunshine 具备 cap_sys_admin能力；仅 Linuxx11基于 XCB，最慢、最耗 CPU，尽量避开；仅 Linux ddxDirectX Desktop Duplication API，Windows 上支持良好；仅 Windows wgc（beta）Windows.Graphics.Capture；仅 Windows；⚠️ 与 Sunshine 服务模式不兼容
7.7 encoder — 强制编码器
- 描述：强制指定编码器。
- 默认：使用第一个可用的编码器。
- 示例：
encoder = nvenc - 可选值：
取值 说明 nvencNVIDIA 显卡 quicksyncIntel 显卡 amdvceAMD 显卡 vaapiLinux VA-API（AMD、Intel） softwareCPU 软件编码
八、NVIDIA NVENC 编码器专项
本节所有选项仅在使用 NVENC 编码器（
encoder = nvenc）时生效。
8.1 nvenc_preset — 性能预设
- 描述：NVENC 性能预设。数值越大压缩率越高（同码率下画质越好），但编码延迟增加。仅在受网络或解码器限制时建议修改；否则提高码率效果相近。
- 默认：
4 - 可选值：
1（P1，最快）…7（P7，最慢），4为默认。
8.2 nvenc_twopass — 双通道模式
- 描述：启用双通道编码，可检测更多运动矢量、更合理分配帧间码率、更严格贴合码率上限。不建议关闭，否则可能偶发码率超调并引发丢包。
- 默认：
quarter_res - 可选值：
disabled（单通道，最快）、quarter_res（双通道，首通道四分之一分辨率，较快）、full_res（双通道，首通道全分辨率，较慢）。
8.3 nvenc_frame_budget_guard — 帧预算保护
- 描述：当预估编码时间无法落在帧间隔的固定比例内时，自动降低性能预设（例如单 NVENC 单元的 GPU 上，4K 120fps 会把默认 P4 压到 P1），确保编码不落后于串流。预估基于较新的高端 GPU 并留保守余量。最新会话的实际生效预设会通过配置 API 的
active_nvenc_frame_budget字段上报，钳制行为以 warning 级别记日志。 - 默认：
enabled - 示例：
nvenc_frame_budget_guard = disabled
8.4 nvenc_spatial_aq — 空间自适应量化
- 描述：默认启用。给画面平坦区域分配更高 QP，在受限码率下提升主观画质。
- 默认：
enabled；示例：nvenc_spatial_aq = enabled
8.5 nvenc_vbv_increase — 单帧 VBV/HRD 放宽
- 描述：单帧 VBV/HRD 上限的百分比放宽。默认 Sunshine 使用单帧 VBV/HRD，即单帧编码大小预期不超过“码率 ÷ 帧率”；放宽后可起到低延迟可变码率作用，但网络无缓冲余量时可能丢包。最大 400（对应编码帧上限放大 5 倍）。
- 默认：
0；范围：0-400；示例：nvenc_vbv_increase = 0
8.6 nvenc_realtime_hags — HAGS 实时调度优先级
- 描述：Windows 启用硬件加速 GPU 调度（HAGS）时，在 NVENC 使用实时 GPU 调度优先级。当前 NVIDIA 驱动在 HAGS 开启、实时优先级且 VRAM 占用接近上限时可能编码器冻结；关闭可将优先级降为 high，规避冻结，代价是 GPU 高负载下采集性能下降。
- 默认：
enabled；示例：nvenc_realtime_hags = enabled - 仅 Windows。
8.7 nvenc_split_encode — 多 NVENC 单元分片编码
- 描述：将每帧编码拆分到多个 NVENC 硬件单元，显著降低编码延迟，压缩效率损失极小；GPU 只有单个 NVENC 单元时忽略该选项。
- 默认：
driver_decides - 可选值：
disabled、driver_decides（由驱动决定）、enabled、two_strips（强制 2 分片，需 2+ 引擎）、three_strips（强制 3 分片，需 3+ 引擎）、four_strips（强制 4 分片，需 4+ 引擎）。 - 仅 Windows。
8.8 nvenc_lookahead_depth — 前瞻帧数
- 描述：编码前瞻帧数，改善复杂场景的运动估计与码率分配，提升画质；值越大延迟越高；
0表示关闭。 - 默认：
0；范围：0-32；示例：nvenc_lookahead_depth = 16 - 需 NVENC SDK 13.0（1202）或更新。
8.9 nvenc_lookahead_level — 前瞻质量等级
- 描述：前瞻质量等级，等级越高画质越好、性能越低；仅在
nvenc_lookahead_depth > 0时生效。 - 默认：
disabled - 可选值：
disabled（等同等级 0）、0（最低质量最快）、1、2、3（最高质量最慢）、autoselect（由驱动自动选择）。 - 需 NVENC SDK 13.0（1202）或更新。
8.10 nvenc_rate_control — 码率控制模式
- 描述：CBR（恒定码率）提供固定码率，适合低延迟串流；VBR（可变码率）按场景复杂度浮动，复杂场景画质更好但码率波动。
- 默认：
cbr - 可选值：
cbr（恒定码率，低延迟最佳）、vbr（可变码率，复杂场景更佳）。
8.11 nvenc_target_quality — VBR 目标质量
- 描述：VBR 模式的目标质量等级，值越低画质越高；
0表示自动选择；仅在 VBR 码率控制下使用。H.264/HEVC 范围0-51，AV1 范围0-63。 - 默认：
0；范围：0-63；示例：nvenc_target_quality = 28
8.12 nvenc_temporal_filter — 时域滤波强度
- 描述：编码前的时域滤波强度，降低噪声、提升压缩效率（尤其自然内容）；等级越高降噪越好但可能轻微模糊。
- 默认：
disabled - 可选值：
disabled（关闭）、0（等同关闭）、4（最大强度）。 - ⚠️ 要求
frameIntervalP >= 5，且与zeroReorderDelay、立体 MVC 不兼容；需 NVENC SDK 13.0（1202）或更新。
8.13 nvenc_latency_over_power — 高功率模式
- 描述：NVIDIA 驱动的自适应 P-State 算法不适合低延迟串流，因此 Sunshine 显式请求高功率模式。⚠️ 不建议关闭，否则编码延迟可能显著增加。
- 默认：
enabled；示例：nvenc_latency_over_power = enabled - 仅 Windows。
8.14 nvenc_opengl_vulkan_on_dxgi — OpenGL/Vulkan 以 DXGI 呈现
- 描述：Sunshine 无法以满帧率采集全屏 OpenGL/Vulkan 程序，除非它们呈现在 DXGI 之上。启用后 Sunshine 将系统全局的 Vulkan/OpenGL 呈现方式改为“Prefer layered on DXGI Swapchain”；这是系统级设置，Sunshine 退出时会还原。
- 默认：
enabled；示例：nvenc_opengl_vulkan_on_dxgi = enabled - 仅 Windows。
8.15 nvenc_h264_cavlc — H.264 偏好 CAVLC
- 描述：NVENC 的 H.264 偏好使用 CAVLC 熵编码而非 CABAC。CAVLC 较陈旧，同画质约多耗 10% 码率，但软件解码略快。
- 默认：
disabled；示例：nvenc_h264_cavlc = disabled - 仅在使用 H.264 格式且编码器为 NVENC 时生效。
8.16 nvenc_cuda_array_input — CUDA Array 输入
- 描述：将 10-bit 4:4:4 帧通过 block-linear CUDA array（而非 pitch-linear 设备指针）送入 NVENC。仅 Windows；要求驱动暴露 NVENC 13.1 或更新，旧驱动上会记录日志并继续使用设备指针。编码器探测始终使用设备指针，因此该选项只影响真实串流会话。
- 默认：
disabled；示例：nvenc_cuda_array_input = disabled - ⚠️ 实验特性：部分驱动在 array 路径下产生重影输出，除非协助测试 4:4:4 路径否则保持关闭；若串流异常，关闭该选项并重启串流。
九、Intel QuickSync 编码器专项
仅在使用
encoder = quicksync时生效。
9.1 qsv_preset — 预设
- 默认：
medium - 可选值（速度→质量）：
veryfast（最快，质量最低）、faster、fast、medium（默认）、slow、slower、veryslow（最慢，质量最高）。
9.2 qsv_coder — 熵编码方式
- 描述：H.264 下的熵编码方式。
- 默认：
auto - 可选值：
auto（由 ffmpeg 决定）、cabac（质量更高）、cavlc（解码更快）。 - 仅在使用 H.264 且编码器为 quicksync 时生效。
9.3 qsv_slow_hevc — 老 GPU 上启用 HEVC
- 描述：在老 Intel GPU（H.264 仅支持低功率编码）上启用 HEVC 编码。⚠️ 开启后串流性能可能显著下降。
- 默认：
disabled；示例：qsv_slow_hevc = disabled
十、AMD AMF 编码器专项
仅在使用
encoder = amdvce时生效。
10.1 amd_usage — 使用场景 profile
- 描述：使用场景 profile 决定一组基础编码参数。后续 AMF 选项会覆盖其中一部分设置，但 profile 中存在无法在其他地方覆盖的隐藏参数。
- 默认：
ultralowlatency - 可选值：
transcoding（转码，最慢）、webcam（摄像头，慢）、lowlatency_high_quality（低延迟高质量，快）、lowlatency（低延迟，更快）、ultralowlatency（超低延迟，最快）。
10.2 amd_rc — 码率控制
- 默认：
vbr_latency - 可选值：
cqp（恒定 QP）、cbr（恒定码率）、vbr_latency（可变码率、延迟受限）、vbr_peak（可变码率、峰值受限）。 - ⚠️
vbr_latency通常效果最佳，但仍可能轻微超调码率；启用 HRD 能更好地约束各码率模式的峰值码率，但部分显卡可能出现编码伪影。
10.3 amd_enforce_hrd — 强制 HRD
- 描述：启用 Hypothetical Reference Decoder（HRD）约束以帮助限制目标码率。⚠️ 已知在某些显卡上引起编码伪影或损害编码质量。
- 默认：
disabled；示例：amd_enforce_hrd = disabled
10.4 amd_quality — 质量 profile
- 默认：
balanced - 可选值：
speed（偏速度）、balanced（均衡）、quality（偏质量）。
10.5 amd_preanalysis — 预分析
- 描述：预分析可提升编码质量，但增加延迟。
- 默认：
disabled；示例：amd_preanalysis = disabled
10.6 amd_vbaq — 方差自适应量化
- 描述：VBAQ 将更多比特优先分配给平滑区域，提升主观视觉质量。
- 默认：
enabled；示例：amd_vbaq = enabled
10.7 amd_coder — 熵编码方式
- 默认：
auto - 可选值：
auto（ffmpeg 决定）、cabac（解码更快）、cavlc（质量更高）。 - 仅在使用 H.264 且编码器为 amdvce 时生效（注意：与 QSV 的
qsv_coder中 cabac/cavlc 的说明相反，AMF 文档标注cabac为“解码更快”、cavlc为“质量更高”，以各编码器实际行为为准）。
十一、VideoToolbox 编码器专项（macOS）
以下选项仅在 macOS 上生效。
11.1 vt_coder — 熵编码方式
- 默认：
auto - 可选值：
auto（ffmpeg 决定）、cabac（解码更快）、cavlc（质量更高）。
11.2 vt_software — 软件编码
- 描述：强制 Video Toolbox 使用软件编码。
- 默认：
auto - 可选值：
auto（ffmpeg 决定）、disabled（禁用软件编码）、allowed（允许软件编码）、forced（强制软件编码）。
11.3 vt_realtime — 实时编码
- 描述：实时编码。⚠️ 关闭可能导致帧编码延迟或丢帧。
- 默认：
enabled；示例：vt_realtime = enabled
十二、Software（软件编码器）专项
仅在使用
encoder = software时生效。预设概念来自 FFmpeg：预设是编码速度与压缩率的折中集合；预设越慢压缩率越好（同目标文件大小/恒定码率下画质更高，恒定质量下节省码率）。原则是：用你能忍受的最慢预设。
12.1 sw_preset — 预设
- 默认：
superfast - 可选值：
ultrafast（最快）、superfast、veryfast、faster、fast、medium、slow、slower、veryslow（最慢）。
12.2 sw_tune — 调优模式
- 描述：按输入内容特征微调编码设置。
- 默认：
zerolatency - 可选值：
取值 适用场景 film高质量电影内容；降低 deblocking animation卡通动画；更高 deblocking 与更多参考帧 grain保留老胶片的颗粒结构 stillimage幻灯片类内容 fastdecode关闭部分滤镜以加速解码 zerolatency快速编码与低延迟串流
十三、配置解析与校验机制（源码视角）
理解配置项的解析路径，有助于排查“为什么我改的值没生效”：
- 读取与合并：
config::parse（src/config.cpp#L1705）先解析命令行（sunshine <path>指定文件、name=value生成覆盖变量），再读取配置文件、将命令行变量insert_or_assign进变量表（src/config.cpp#L1780-L1782），最后统一交给apply_config。 - 类型化校验：
apply_config中各类参数使用专门的解析辅助函数：string_f（字符串）、bool_f（enabled/disabled）、int_between_f（限定区间整数，如hevc_mode/av1_mode的{0,3}、fec_percentage的{1,255}）、string_restricted_f（白名单字符串，如locale）、path_f（路径）、list_prep_cmd_f（prep 命令列表）、map_int_int_f（键值映射，如keybindings）。超出范围或非法取值会被拒绝并记录 warning，然后回退默认值。 - 显示设备配置的枚举化：Windows 专属的
dd_*选项在 src/display_device/parsed_config.h 中建模为device_prep_e（拓扑准备：ensure_active/ensure_primary/ensure_only_display等）、resolution_change_e、refresh_rate_change_e、hdr_prep_e，由 src/display_device/parsed_config.cpp#L452-L499 的*_from_view做字符串→枚举转换，并在 src/platform/windows/display_device/settings.cpp 中执行拓扑、模式、HDR 的保存/修改/回滚。 - 未知配置项告警：当日志级别 ≤
info时，未识别的配置项会以Warning: Unrecognized configurable option <a href="https://link.gitcode.com/i/28ada3ee37912753717634db7d90634a" target="_blank">...]打印（[src/config.cpp#L1697-L1699）——排查拼写错误最直接的手段。
十四、常见调参场景速查
- 低延迟优先：
nvenc_preset = 1、nvenc_twopass = disabled、nvenc_split_encode = enabled（需多 NVENC 单元）、保持nvenc_latency_over_power = enabled、sw_tune = zerolatency（软件编码时）。 - 画质优先（带宽充足）：提高
max_bitrate或让 Moonlight 自行请求码率（max_bitrate = 0），nvenc_preset保持默认或小幅上调。 - 多显示器/虚拟显示器串流：用
output_name选择目标显示器；Windows 下用dd_configuration_option = ensure_only_display等模式在串流期间独占显示器，配dd_config_revert_delay/dd_config_revert_on_disconnect控制回滚时机；VDD 场景可关注dd_wa_hdr_toggle_delay缓解 HDR 伪色。 - 音频静音串流：
audio_sink选实际回环设备，virtual_sink指定 Steam Streaming Speakers / Virtual Audio Cable，并配合install_steam_audio_drivers（Windows）。 - 互联网串流：
upnp = enabled（或手动端口映射）、wan_encryption_mode = 2强制加密、external_ip指定公网 IP。 - 输入异常：键盘错位关
always_send_scancodes（Windows）；无法发送 Win 键用key_rightalt_to_key_win或自定义keybindings；老应用滚动过快关high_resolution_scrolling。
提示：本文所有参数值均以当前仓库 docs/configuration.md 与 src/config.cpp 等源码为准；不同版本、不同平台的可用取值可能不同，修改后建议查看启动日志确认参数被正确识别。
登录后查看全文