Foundation Sunshine 快速上手指南：多平台安装、初始配置与 Moonlight 串流实战

原创2026-10-02 09:22:112,175 阅读

文章标签：音视频后端桌面应用

Foundation Sunshine 快速上手指南：多平台安装、初始配置与 Moonlight 串流实战

Foundation Sunshine 是一款基于 LizardByte/Sunshine 的增强型自托管游戏串流主机，面向 Moonlight 客户端提供 HDR10/HDR Vivid、虚拟显示器、增强音频与优化编码器等能力。本文以官方入门文档为主体，覆盖 Linux、macOS、Windows 与 Docker 四种部署路径，完整讲解从下载安装、初始设置、Web UI 配置、PIN 配对到 HDR 串流的全流程，并深入仓库源码解析启动链路、配置解析与 CLI 子命令的底层实现，帮助读者一次性完成从"装起来"到"跑起来、串起来"的全部步骤。

获取发行版：优先使用官方二进制

官方文档推荐的运行方式是使用最新发行版中随附的二进制文件，而不是自行编译。Sunshine 的发行二进制为每次 release 生成，覆盖 Linux、macOS 和 Windows 三个平台。

需要说明的是：

预发布（Pre-release）版本同样可用，但应视为 beta 质量；由于合并节奏较快，预发布版本可能缺失部分发行产物。
第三方打包也存在（详见 Third Party Packages），但官方不对第三方包提供任何支持，遇到问题时应优先换用官方二进制排查。

安装

Docker（不推荐用于大多数用户）

官方文档明确警告：Docker 镜像不推荐用于大多数用户。镜像主要用于在自己的 Docker 项目中方便地引入最新 Sunshine 发行版，本身仍属实验性方案。

在 DOCKER_README.md 中给出了镜像的 tag 规则：必须用 <SUNSHINE_VERSION>-<SUNSHINE_OS> 组合，例如 latest-ubuntu-24.04。SUNSHINE_VERSION 可以是 latest、master、vX.X.X 或 commit hash；SUNSHINE_OS 后缀包括 archlinux、debian-bookworm、fedora-39、fedora-40、ubuntu-22.04、ubuntu-24.04。注意从 v0.18.0 起 tag 命名已变更，不能再使用单纯的 latest、master、vX.X.X。

一个典型的 docker run 部署命令如下（端口与卷映射均为必需）：

docker run -d \
  --device /dev/dri/ \
  --name=<image_name> \
  --restart=unless-stopped \
  --ipc=host \
  -e PUID=<uid> \
  -e PGID=<gid> \
  -e TZ=<timezone> \
  -v <path to data>:/config \
  -p 47984-47990:47984-47990/tcp \
  -p 48010:48010 \
  -p 47998-48000:47998-48000/udp \
  <image>

其中端口与参数的作用如下：

参数	作用	示例	必需
`-p <port>:47990`	Web UI 端口（容器内必须为 47990，外部可改，如 `-p 8080:47990`）	`47990`	是
`-v <path to data>:/config`	数据卷映射，配置文件保存在容器 `/config` 目录	`/home/sunshine`	是
`-e PUID=<uid>`	运行用户 ID，避免宿主机与容器间权限问题	`1001`	否
`-e PGID=<gid>`	运行组 ID	`1001`	否
`-e TZ=<timezone>`	时区（IANA 时区名）	`America/New_York`	否

在 src_assets 之外，仓库的 docker 目录还提供了 ubuntu-22.04、ubuntu-24.04、debian-bookworm、fedora-39、fedora-40、archlinux 等基础镜像的 Dockerfile，可据此理解各发行版打包差异。

Linux

CUDA 兼容性（NVFBC 捕获）

CUDA 用于 NVFBC 屏幕捕获。不同发行版包内置的 CUDA 版本对应不同的最低驱动与计算能力要求，选择安装包前请对照下表，并可参考 NVIDIA 官方的 CUDA GPU 支持矩阵来交叉核对显卡的 Compute Capability。

CUDA 版本	最低驱动	CUDA Compute Capabilities	软件包
11.8.0	450.80.02	35;50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine.AppImage
11.8.0	450.80.02	35;50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine-ubuntu-22.04-{arch}.deb
11.8.0	450.80.02	35;50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine-ubuntu-24.04-{arch}.deb
12.0.0	525.60.13	50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine_{arch}.flatpak
12.0.0	525.60.13	50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine-debian-bookworm-{arch}.deb
12.4.0	525.60.13	50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine-fedora-39-{arch}.rpm
12.5.1	525.60.13	50;52;60;61;62;70;72;75;80;86;87;89;90	sunshine.pkg.tar.zst
n/a	n/a	n/a	sunshine-fedora-40-{arch}.rpm

注意：{arch} 指操作系统的 CPU 架构（如 amd64 / aarch64），需替换为实际值。

AppImage

官方提示：如果发行版提供了特定软件包，应优先使用发行版包而非 AppImage。AppImage 的受支持发行版矩阵如下：

✖ Debian bullseye
✔ Debian bookworm
✔ Debian trixie
✔ Debian sid
✔ Ubuntu noble
✔ Ubuntu jammy
✖ Ubuntu focal
✖ Ubuntu bionic
✖ Ubuntu xenial
✖ Ubuntu trusty
✖ CentOS 7

安装到主目录并执行：

cd ~
wget <release 下载地址>/sunshine.AppImage
./sunshine.AppImage --install

运行与卸载：

# 安装并运行
./sunshine.AppImage --install && ./sunshine.AppImage

# 卸载
./sunshine.AppImage --remove

ArchLinux

官方不提供任何 AUR 包的支持。两种官方路径：

安装预编译包：按官方 pacman 仓库说明添加仓库后：

pacman -S sunshine

从 PKGBUILD 归档安装：

wget <release 下载地址>/sunshine.pkg.tar.gz
tar -xvf sunshine.pkg.tar.gz
cd sunshine

# 安装可选依赖
pacman -S cuda            # Nvidia GPU 编码支持
pacman -S libva-mesa-driver  # AMD GPU 编码支持

makepkg -si

卸载：

pacman -R sunshine

Debian / Ubuntu

下载 sunshine-{distro}-{distro-version}-{arch}.deb 后安装：

sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb

其中 {distro-version} 是官方打包所基于的发行版版本，{arch} 是你的系统架构。也可直接双击 deb 文件查看包详情并开始安装。

卸载：

sudo apt remove sunshine

Fedora

先添加 rpmfusion 仓库：

sudo dnf install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

然后下载 sunshine-{distro}-{distro-version}-{arch}.rpm 并安装：

sudo dnf install ./sunshine-{distro}-{distro-version}-{arch}.rpm

卸载：

sudo dnf remove sunshine

Flatpak

官方提示：优先使用发行版特定包而非 Flatpak；同时注意以下指令针对的是最新发行版提供的 Flatpak 包，可能与 Flathub 仓库中的版本不一致。使用前需先安装 Flatpak 运行时。

# 下载 sunshine_{arch}.flatpak（{arch} 替换为系统架构）

# 系统级安装
flatpak install --system ./sunshine_{arch}.flatpak

# 用户级安装
flatpak install --user ./sunshine_{arch}.flatpak

# 必须执行的附加安装（安装辅助组件）
flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine

运行方式分两种捕获后端：

# NVFBC 捕获（仅 X11）
flatpak run dev.lizardbyte.app.Sunshine

# KMS 捕获（Wayland 与 X11）
sudo -i PULSE_SERVER=unix:/run/user/$(id -u $whoami)/pulse/native flatpak run dev.lizardbyte.app.Sunshine

卸载：

flatpak run --command=remove-additional-install.sh dev.lizardbyte.app.Sunshine
flatpak uninstall --delete-data dev.lizardbyte.app.Sunshine

Homebrew（Linux，实验性）

需要先安装 Homebrew：

brew tap LizardByte/homebrew
brew install sunshine

卸载：

brew uninstall sunshine

macOS

官方声明：macOS 上的 Sunshine 仍属实验性，手柄（Gamepad）暂不可用。

Homebrew

brew tap LizardByte/homebrew
brew install sunshine

如需 beta 版本，将上面命令中的 sunshine 替换为 sunshine-beta 即可。卸载命令为 brew uninstall sunshine。

MacPorts（Portfile）

先更新 MacPorts 源：

sudo nano /opt/local/etc/macports/sources.conf

在以 rsync 开头的行下方添加一行（把 <username> 替换为你的用户名）：

file:///Users/<username>/ports

Ctrl+x，然后 Y 退出并保存。接着下载安装：

mkdir -p ~/ports/multimedia/sunshine
cd ~/ports/multimedia/sunshine
curl -OL <release 下载地址>/Portfile
cd ~/ports
portindex
sudo port install sunshine

可选：安装为服务（开机自启）：

sudo port load sunshine

卸载：

sudo port uninstall sunshine

Windows

安装器（推荐）

下载并安装 sunshine-windows-installer.exe。安装时应仔细勾选或取消勾选所需组件，不要盲目安装或启用功能。

卸载：在 Windows 的"已安装的应用"列表中找到 Sunshine，从溢出菜单中选择"卸载"即可（不同 Windows 版本卸载步骤可能略有差异）。

在仓库中，Windows 安装器涉及的辅助脚本与组件位于 src_assets/windows/misc 目录：包括防火墙规则脚本 firewall/add-firewall-rule.bat、firewall/delete-firewall-rule.bat，服务脚本 service/install-service.bat、service/autostart-service.bat、service/uninstall-service.bat，以及虚拟显示器（vdd/）、虚拟手柄（gamepad/）、虚拟鼠标（vmouse/）、虚拟扬声器（vsink/）等驱动安装脚本，可对照了解安装器各选项对应的实际操作。

Standalone（精简版）

官方警告：使用此精简包会导致性能下降，不推荐大多数用户使用，且不提供支持。

下载并解压 sunshine-windows-portable.zip。
以管理员身份打开命令提示符。

配置防火墙规则：

cd /d {path to extracted directory}

# 安装
scripts/add-firewall-rule.bat

# 卸载
scripts/delete-firewall-rule.bat

安装虚拟手柄支持：

cd /d {path to extracted directory}

# 安装
scripts/install-gamepad.bat

# 卸载
scripts/uninstall-gamepad.bat

安装 Windows 服务：

cd /d {path to extracted directory}

# 安装
scripts/install-service.bat
scripts/autostart-service.bat

# 卸载
scripts/uninstall-service.bat

卸载精简版只需删除包含 sunshine.exe 的解压目录。

从源码角度，Windows 版在 src/main.cpp 中做了多项平台适配：启动时通过 SetDefaultDllDirectories 限制 DLL 搜索路径以规避不安全 PATH 注入、提前启用进程级深色模式（win_dark_mode::enable_process_dark_mode()）、创建隐藏的 Session Monitor 窗口以在注销/关机时优雅退出，并在存在 NVIDIA 显卡时通过 nvprefs 模块恢复上次异常退出遗留的驱动设置并改写应用程序配置。

初始设置

Linux

KMS 捕获（必需步骤）

官方警告：如果跳过此步骤，大多数基于 Wayland 的桌面环境的捕获会失败。

sudo setcap cap_sys_admin+p $(readlink -f $(which sunshine))

cap_sys_admin 的能力与 root 相当，但设置后无需以 root 身份运行程序，这允许 Sunshine 使用 KMS 捕获。

X11 捕获

X11 捕获可能需要移除 KMS 捕获设置的能力：

sudo setcap -r $(readlink -f $(which sunshine))

服务方式运行

# 启动一次
systemctl --user start sunshine

# 开机自启
systemctl --user enable sunshine

macOS

首次启动 Sunshine 时，系统会请求授予屏幕录制与麦克风访问权限。受系统限制，Sunshine 在 macOS 上只能访问麦克风；要串流系统音频，需要使用 Soundflower 或 BlackHole 这类虚拟声卡将系统音频路由为可捕获的音频源。

另需注意 macOS 的按键映射限制：

Moonlight 不会转发 Command 键；
右侧 Option 键会被映射为 CMD 键；
手柄目前不受支持。

日常使用

基本运行

如果 Sunshine 未安装为服务（后台进程，Windows 安装器默认安装为服务），则直接运行：

sunshine

官方提示：不建议同时运行多个 Sunshine 实例。

指定配置文件

sunshine <directory of conf file>/sunshine.conf

两个关键行为值得留意：

不指定配置文件时，将使用默认位置（在 src/config.cpp 中为平台 appdata 目录下的 sunshine.conf）；
指定的配置文件若不存在会被自动创建，而不是报错退出。

这一行为在源码中有清晰对应：config::parse()（src/config.cpp）会先确保 appdata 目录存在，若目标配置文件不存在则创建一个空文件，再读取并解析内容，最后将命令行传入的 key=value 选项覆盖写入的配置值。命令行位置参数（非 -- 开头、不含 = 的裸参数）被解释为配置文件路径。

通过 SSH 启动（Linux/X11）

已登录到主机图形会话时：

ssh <user>@<ip_address> 'export DISPLAY=:0; sunshine'

若只有 tty 登录，可先用 startx 启动 X server 再执行 Sunshine；建议在 startx 与 sunshine 之间加入 sleep 等待显示就绪：

ssh <user>@<ip_address> 'startx &; export DISPLAY=:0; sunshine'

也可以利用 ~/.bash_profile 或 ~/.bashrc 预先设置 DISPLAY 变量。

Web UI 配置与 PIN 配对

Sunshine 通过 Web UI 配置，默认地址为 https://localhost:47990，可将 localhost 替换为内网 IP。浏览器可能提示"不安全网站"，这是自签名 SSL 证书所致，可忽略；首次运行时务必记下你创建的用户名和密码。

在 src/confighttp.cpp 中，配置服务通过 net::map_port(PORT_HTTPS) 确定监听端口并启动 HTTPS server，这正是 Web UI 端口的实现来源；同时该服务默认只监听回环/内网地址，相关监听地址与端口均可通过配置调整。

配对与首次串流步骤：

在 Web UI 中添加要串流的游戏和应用。
按需调整各项配置。
在 Moonlight 客户端中可能需要手动添加主机。
当 Moonlight 提示输入 PIN 时：
- 登录 Web UI；
- 在导航栏进入 "PIN" 页面；
- 输入 PIN 并按回车，应看到成功提示；
- 回到 Moonlight 选择列出的某个应用开始串流。

命令行参数

获取完整参数列表：

# 通用
sunshine --help

# AppImage
./sunshine.AppImage --help

# Flatpak
flatpak run --command=sunshine dev.lizardbyte.app.Sunshine --help

从源码看，src/main.cpp 注册了四个内置子命令：creds（凭据管理）、help、version、restore-nvprefs-undo（Windows 下恢复 NVIDIA 控制面板撤销记录）。--version 会直接打印 PROJECT_NAME version: PROJECT_VER 并退出；config::parse 在遇到 --help 时打印帮助并返回。未知子命令会以退出码 7 结束并列出可能的命令。

快捷键

所有快捷键都以 Ctrl+Alt+Shift 开头，与 Moonlight 一致：

Ctrl+Alt+Shift+N：隐藏/显示光标（对 Moonlight 的远程桌面模式很有用）
Ctrl+Alt+Shift+F1/F12：切换串流所监视的显示器

应用列表（Application List）

应用应通过 Web UI 配置；
需要基本的"工作目录 + 命令"概念；
可以使用环境变量代替值：$(HOME) 会被替换为 $HOME 的值；$$ 会被替换为 $，例如 $$(HOME) 最终变成 $(HOME)；
env 为 Sunshine 运行的应用添加或覆盖环境变量，此字段只能直接修改 apps.json 文件。仓库中的默认应用模板位于 src_assets/linux/assets/apps.json、src_assets/windows/assets/apps.json 与 src_assets/macos/assets/apps.json。

使用注意事项

Windows 捕获后端：Sunshine 在 Windows 上使用 Desktop Duplication API，它只能捕获用于显示的 GPU。若要在 eGPU 上捕获并编码，请给它接上显示器或 HDMI 虚拟显示器（dummy dongle）并把游戏运行在该显示器上。
应用互斥：启动新应用时，若已有应用在运行，它会被终止。
prep-commands 失败：任何 prep-commands 失败都会中止应用启动。
应用退出即断流：应用关闭后流随之关闭。例如把 steam 配置为 cmd 而非 detached，流会立即失败——这是 Steam 进程的执行方式决定的，其他应用也可能类似；detached 应用不受此限制。
Desktop 应用：与普通应用相同但没有任何命令，它不启动应用、直接开始串流。若误删，可新建一个名为 "Desktop"、图片路径为 "desktop.png" 的应用恢复。
Linux Flatpak：命令前必须加 flatpak-spawn --host 前缀。

HDR 支持

HDR 内容串流在 Windows 主机上正式支持，在 Linux 主机上为实验性支持。

通用要求与说明：

主机操作系统必须已激活 HDR，可能需要 HDR 显示器或 EDID 模拟器（emulator dongle）接入主机；
Moonlight 客户端设置中必须启用 HDR 选项，否则串流将是 SDR（且若主机处于 HDR 状态画面大概率过曝）；
良好的 HDR 体验依赖操作系统与游戏内的正确 HDR 校准，客户端与主机显示器的校准可能差异显著；
可能需要针对客户端显示器的 HDR 亮度能力，在游戏内调节亮度滑块或 HDR 校准选项；
部分 GPU 的硬件编码器在 HDR 串流时可能比 SDR 产生更低的画质或编码性能。

平台差异：

Windows：支持支持 HEVC Main 10 或 AV1 10-bit 编码的 Intel、AMD、NVIDIA 显卡。官方建议把 Windows HDR 校准应用串流到客户端完成校准并保存 HDR 校准配置文件。使用 NVIDIA 专属 NVAPI HDR（而非原生 Windows HDR）的老游戏可能在 HDR 下显示异常。
Linux：支持通过 VAAPI 编码 HEVC Main 10 或 AV1 10-bit 的 Intel 与 AMD 显卡；必须使用 KMS 捕获后端（NvFBC、X11 等其他捕获方式不支持 HDR）；需要一个支持 HDR 渲染的桌面环境，如 Gamescope 或 KDE Plasma 6。

本项目在 HDR 链路上的增强可参考仓库 README.md 与相关设计文档，包括 PQ/HLG 双格式编码、逐帧亮度分析与 HDR10+/HDR Vivid 动态元数据注入等。

教程与指南

视频教程与图文指南均由社区生成，可参见仓库内的 guides.md；完整的变更历史见 changelog.md。

附录：源码级启动链路速览

理解上述命令背后的实现，可以更从容地排障。以 src/main.cpp 为线索，启动流程大致如下：

扫描 --version 参数并输出版本后提前退出；
调用 config::parse(argc, argv) 解析配置文件与命令行覆盖项（逻辑见 src/config.cpp）；
初始化日志系统，随后输出项目版本与发行商信息；若存在被命令行/配置覆盖的设置，会以 JSON 形式写入日志（凭证类配置如 widget_token 会脱敏为 <redacted>）；
若命令行指定了子命令（creds/help/version/restore-nvprefs-undo），分派执行；
初始化显示设备会话（display_device::session_t::init()），并在 Windows 上执行 NVIDIA 控制面板设置恢复与写入；
启动编码器探测 probe_encoders_with_watchdog()：探测期间若有 30 秒无返回，会持续输出告警日志提示"图形驱动调用可能卡死"，帮助定位"启动成功但无法串流"类问题；
注册 SIGINT/SIGTERM 处理器，10 秒内未能优雅退出则强制终止（Windows 控制台关闭事件也走同一路径）。

参考文件

入门文档原文：docs/getting_started.md
项目总览：README.md
Docker 部署说明：DOCKER_README.md
第三方包说明：docs/third_party_packages.md
配置指南：docs/configuration.md
构建说明：docs/building.md
使用指南：docs/guides.md
变更日志：docs/changelog.md
串流性能调节：docs/performance_tuning.md

登录后查看全文

音视频后端桌面应用

foundation-sunshine

Foundation Sunshine 快速上手指南：多平台安装、初始配置与 Moonlight 串流实战

Foundation Sunshine 快速上手指南：多平台安装、初始配置与 Moonlight 串流实战

获取发行版：优先使用官方二进制

安装

Docker（不推荐用于大多数用户）

Linux

CUDA 兼容性（NVFBC 捕获）

AppImage

ArchLinux

Debian / Ubuntu

Fedora

Flatpak

Homebrew（Linux，实验性）

macOS

Homebrew

MacPorts（Portfile）

Windows

安装器（推荐）

Standalone（精简版）

初始设置

Linux

KMS 捕获（必需步骤）

X11 捕获

服务方式运行

macOS

日常使用

基本运行

指定配置文件

通过 SSH 启动（Linux/X11）

Web UI 配置与 PIN 配对

命令行参数

快捷键

应用列表（Application List）

使用注意事项

HDR 支持

教程与指南

附录：源码级启动链路速览

参考文件

相关推荐

热门文章