Sunshine 快速上手跨平台安装、系统服务部署与首次配置全流程指南【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是一个自托管的 Moonlight 串流主机程序本文基于官方入门文档 docs/getting_started.md 完整梳理了在 FreeBSD、Linux、macOS、Windows 各平台上的安装包选择、安装命令、系统服务配置、Web UI 首次配置、命令行用法与快捷键、应用管理规则及 HDR 串流支持等全部内容并结合仓库源码补充了端口布局、服务单元文件与命令行参数解析的实现依据。读完本文你可以独立完成任意平台的 Sunshine 部署理解其默认端口与配置文件的生成机制并排除首次连接 Moonlight 客户端时的常见问题。安装前的准备选择正确的发行方式官方推荐运行 Sunshine 的方式是使用最新正式版本发布包中附带的二进制发行版。每个 release 都会构建对应的二进制包覆盖 FreeBSD、Linux、macOS 与 Windows 四大平台。此外还可以获取预发布Pre-release构建但它们应当被视为 beta 版本——由于合并变更的节奏更快预发布产物在个别版本中可能缺失仅建议在明确需要尝鲜时使用。需要注意的是社区中也存在第三方打包的 Sunshine 包可参见 第三方包说明。官方明确声明不为第三方包提供任何形式的支持生产环境建议一律使用官方发布产物。分平台安装Docker不推荐大多数用户使用[!WARNING] 官方不推荐大多数用户使用 Docker 镜像。Docker 镜像托管在 Docker Hub 与 ghcr.io 上仓库组织 LizardByte 名下完整说明见 DOCKER_README.md。仓库内 docker/ 目录提供了 ubuntu-22.04/24.04/26.04 与 debian-trixie 的 Dockerfile可对照了解镜像构建方式。FreeBSD安装下载与架构对应的.pkg包然后执行sudo pkg install ./Sunshine-FreeBSD-14.4-{arch}.pkg架构包名amd64/x86_64Sunshine-FreeBSD-14.4-amd64.pkgarm64/aarch64Sunshine-FreeBSD-14.4-aarch64.pkg卸载sudo pkg delete SunshineLinuxLinux 的安装方式最多官方按发行形态分为 AppImage、Arch、Debian/Ubuntu、Fedora/OpenSUSE、Flatpak 与 Homebrew 六类。CUDA 兼容性CUDA 用于 NVFBC 画面捕获。官方 LizardByte 发布包已内置所需 CUDA 运行库使用官方包无需单独安装 CUDA如果你自行编译则需按下表核对显卡的 Compute Capability 与驱动版本CUDA 版本最低驱动支持 Compute Capabilities覆盖的包形态13.1.1590.48.0150; 52; 60; 61; 62; 70; 72; 75; 80; 86; 87; 89; 90; 100; 101; 103; 120; 121AppImage、Ubuntu 22.04/24.04 deb、Debian trixie deb、Flatpak、Fedora/OpenSUSE Copr、Arch PKGBUILDAppImage[!CAUTION] 如果系统有发行版专属包请优先使用专属包。AppImage不支持 KMS 捕获。AppImage 基于 Ubuntu 22.04 构建要求glibc ≥ 2.35与libstdc ≥ 3.4.11。# 安装下载到主目录后执行 cd ~ wget latest-release/sunshine.AppImage ./sunshine.AppImage --install # 运行 ./sunshine.AppImage --install ./sunshine.AppImage # 卸载 ./sunshine.AppImage --removeArch Linux[!CAUTION] AUR 编译安装风险自担。预构建包方式先按 LizardByte pacman-repo 的说明添加仓库pacman -S sunshinePKGBUILD 归档方式wget latest-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{distro-version}是构建该包所用的发行版版本{arch}是系统架构后执行sudo dpkg -i ./sunshine-{distro}-{distro-version}-{arch}.deb卸载sudo apt remove sunshine。图形环境下也可以直接双击 deb 文件查看详情并启动安装。Fedora / OpenSUSE[!TIP] 包名区分大小写。下载Sunshine-{version}.{distroversion}.{arch}.rpm后执行sudo dnf install ./Sunshine-{version}.{distro}.{arch}.rpm卸载sudo dnf remove sunshine。CopR 源安装[!IMPORTANT] 稳定版 CopR 构建仅在 Sunshine 发布时间晚于对应 Fedora 版本发布时存在因此官方更常建议使用 beta copr无需频繁更新但极少数情况下可能遭遇破坏性变更。# 1. 启用 copr 仓库二选一 sudo dnf copr enable lizardbyte/stable # 或 sudo dnf copr enable lizardbyte/beta # 2. 安装 sudo dnf install Sunshine卸载sudo dnf remove Sunshine。仓库中的 copr spec 文件 展示了该包的构建定义。Flatpak[!CAUTION] 有发行版专属包时请优先使用专属包。Flatpak不支持 KMS 捕获。系统级安装Flathub 或本地sunshine_{arch}.flatpakflatpak install --system flathub dev.lizardbyte.app.Sunshine flatpak install --system ./sunshine_{arch}.flatpak用户级安装flatpak install --user flathub dev.lizardbyte.app.Sunshine flatpak install --user ./sunshine_{arch}.flatpak必做的额外步骤安装或更新 Flatpak 后必须运行特权宿主机 udev 规则同步脚本脚本源在 additional-install.shflatpak run --commandadditional-install.sh dev.lizardbyte.app.Sunshine运行与卸载flatpak run dev.lizardbyte.app.Sunshine # X11 使用 NVFBCWayland 使用 XDG Portal 捕获 flatpak run --commandremove-additional-install.sh dev.lizardbyte.app.Sunshine flatpak uninstall --delete-data dev.lizardbyte.app.SunshineHomebrewLinux 上为实验性支持brew update brew upgrade brew tap LizardByte/homebrew brew install sunshine sudo $(brew --prefix sunshine)/bin/postinst卸载brew uninstall sunshine。测试版可将命令中的sunshine替换为sunshine-beta。macOS[!IMPORTANT] Sunshine 在 macOS 上处于实验阶段手柄不可用。DMG 安装按架构下载arm64 Apple Silicon / x86_64 IntelSunshine-macOS-{arch}.dmg打开后把Sunshine.app拖入Applications文件夹并弹出镜像。卸载退出程序后从「应用程序」文件夹拖入废纸篓。Homebrewbrew update brew upgrade brew tap LizardByte/homebrew brew install sunshine # 卸载brew uninstall sunshine测试版同样可用sunshine-beta替代。Windows[!NOTE] Sunshine 支持 Windows ARM64但属于实验性支持该版本不能正确支持 GPU 调度与任何硬件加速。安装包推荐架构安装包AMD64/x64Sunshine-Windows-AMD64-installer.msiARM64Sunshine-Windows-ARM64-installer.msi[!CAUTION] 未来将以 msi 安装包为主。使用其他类型安装方式之前应手动卸载此前的安装。 请谨慎勾选/取消勾选安装选项不要盲目启用功能。安装日志位于%%TEMP%/Sunshine/logs/install/。卸载入口在系统「设置 → 应用」中不同 Windows 版本的卸载步骤略有差异。独立版lite 精简版[!WARNING] 相比安装包lite 版性能会下降官方不推荐大多数用户使用且不提供支持。下载并按架构解压后以管理员身份打开命令行依次执行防火墙规则与服务脚本脚本源文件见 src_assets/windows/misc/ 目录:: 防火墙规则 cd /d {解压目录} scripts\add-firewall-rule.bat :: 安装 scripts\delete-firewall-rule.bat :: 卸载 :: Windows 服务 cd /d {解压目录} scripts\install-service.bat scripts\autostart-service.bat :: 安装 scripts\uninstall-service.bat :: 卸载初始配置FreeBSD虚拟输入设备[!IMPORTANT] 要使用虚拟输入设备键盘、鼠标、手柄必须把当前用户加入input组。安装过程会创建input组并配置/dev/uinput权限执行以下命令后需重新登录生效pw groupmod input -m $USERLinux用户服务一次性启动systemctl --user start app-dev.lizardbyte.app.Sunshine开机自启systemctl --user --now enable app-dev.lizardbyte.app.Sunshine[!NOTE] 服务命名为app-dev.lizardbyte.app.Sunshine是为了提升与 XDG Desktop Portal 的兼容性同时保留了sunshine.service别名。从源码可以印证这一点服务单元模板 app-dev.lizardbyte.app.Sunshine.service.in 中定义了Aliassunshine.serviceWantedBygraphical-session.target使其挂接图形会话ExecStartPre/bin/sleep 5用于避免桌面初始化完成前抢先启动Restarton-failure保证失败后 5 秒自动重启。macOS系统权限与音频首次启动会请求屏幕录制与麦克风权限。macOS 14.0 (Sonoma) 及更新版本可通过 Apple Audio Tap API 原生捕获系统声音此时只需将Audio Sink设置留空若偏好自行管理回环设备如 Soundflower、BlackHole可将其设备名填入 audio_sink 配置项。[!NOTE] Command 键不会被 Moonlight 转发右 Option 键映射为 CMD 键。 [!CAUTION] 当前版本不支持手柄。macOS 音频捕获的实现可参见 src/platform/macos/av_audio.mm 等源码文件。Windows虚拟输入驱动Windows 上的虚拟输入基于 libvirtualhid需要单独安装 Virtual HID Driver才能启用基于驱动的 Raw Input 键盘/鼠标以及完整的虚拟手柄支持。ViGEmBus 仅作为 libvirtualhid 不可用时针对 Xbox 360 与 DualShock 4 手柄的受限回退该回退逻辑可参见 src/platform/virtualhid_input.cpp 与 src/platform/windows/input.cpp 中对 ViGEm 的引用。要求 Virtual HID Driver 版本不低于2026.829.2338.54更早版本的 Windows 控制与 broker 协议不兼容必须与 Sunshine 内嵌的 libvirtualhid 库同步升级。本地开发驱动的0.0.0.*版本仍受支持。相比 ViGEmBus 回退Virtual HID Driver 支持创建 Xbox One、Xbox Series、DualSense、Switch Pro、Generic 手柄并可在支持时暴露运动、触控板、LED、自适应扳机等控制器特性。在兼容驱动与有效许可证下常规按键通过真实 HID 键盘暴露Raw Input 应用可直接接收Unicode 文本输入及超出支持 HID 键盘页的按键仍走 Windows 注入。驱动/中间层/许可证不可用时libvirtualhid 保留 SendInput 回退。相对鼠标移动、按键与滚轮通过真实 HID 鼠标暴露绝对鼠标定位仍使用 Windows 输入注入。驱动级设备含手柄、Raw Input 键鼠需要有效的机器许可证。Sunshine 会在 Web UI 的 Troubleshooting 页与托盘「Virtual HID Driver」子菜单中显示许可证状态未激活机器上启动时点击托盘通知即可在 Web UI 中打开激活与购买选项。许可操作成功后 Sunshine 会重建共享键鼠切换 HID/SendInput 路径无需重启 Sunshine。安装或更新虚拟输入驱动后建议重启计算机。启动与使用基本用法若未以服务方式安装/运行Windows 安装包默认以服务模式运行不建议运行多个 Sunshine 实例直接执行sunshine指定配置文件sunshine 配置文件所在目录/sunshine.conf[!NOTE] 此步骤可省略。不指定时使用默认位置指定的配置文件若不存在会被自动创建。源码印证参数解析逻辑位于 src/config.cpp——命令行中不含的第一个非选项参数即被识别为配置文件路径约 L1947-L1949加载前会确保 appdata 目录存在并在配置文件缺失时自动创建空文件约 L1971-L1977默认配置路径为appdata()/sunshine.conf约 L877。通过 SSH 启动Linux/X11已登录宿主机显示会话时ssh userip_address export DISPLAY:0; sunshine仅有 tty 时可先用startx拉起 X server必要时在两者之间加sleep等待显示就绪ssh userip_address startx ; export DISPLAY:0; sunshine[!TIP] 也可以在~/.bash_profile或~/.bashrc中设置DISPLAY变量。命令行参数查看可用参数不同运行形态的入口不同sunshine --help # 常规安装 ./sunshine.AppImage --help # AppImage flatpak run --commandsunshine dev.lizardbyte.app.Sunshine --help # Flatpak从源码结构看--help输出由 src/logging.cpp 的print_help生成参数解析与选项注册集中在 src/config.cpp例如port选项的合法区间由 HTTP 与 RTSP 端口偏移共同约束约 L1810-L1812。Web UI 配置流程Sunshine 通过 Web UI 配置默认地址为https://localhost:47990可用内网 IP 替换 localhost。[!NOTE] 浏览器提示不安全网站属于正常现象原因是使用了自签名 SSL 证书。 [!CAUTION] 首次运行请记下创建的账号与密码。端口布局的实现依据基础端口默认值为47989src/config.cpp 约 L879Web UI 运行在port 1上因此为 47990约 L1814-L1819代码注释明确Web UI runs on port 1RTSP 建连监听使用偏移 21src/rtsp.h 中RTSP_SETUP_PORT 21各监听端口在 src/network.cpp 中统一按config::sunshine.port offset映射。配置步骤通过导航栏下拉菜单切换主题添加游戏与应用程序按需调整配置项可搜索栏定位选项在Featured Apps标签页查找 Moonlight 客户端等工具Moonlight 中可能需要手动添加 PCMoonlight 请求输入 PIN 时登录 Web UI → 导航栏进入 PIN → 输入 PIN 并按Enter为设备填写名称随后应出现成功提示 → 回到 Moonlight 选择要串流的应用遇到问题时查看Troubleshooting标签页的日志逐条浏览警告/错误信息定位问题。快捷键所有快捷键均以CtrlAltShift起始与 Moonlight 一致CtrlAltShiftN显示/隐藏鼠标光标对 Moonlight 远程桌面模式有用CtrlAltShiftF1/CtrlAltShiftF12切换用于串流的显示器。应用列表规则应用应通过 Web UI 配置需要理解工作目录与命令的基本概念命令中可使用环境变量替代字面值$(HOME)会被替换为$HOME的值$$会被替换为$例如$$(HOME)最终得到$(HOME)env字段可为 Sunshine 启动的命令/应用添加或覆盖环境变量该字段只能直接修改apps.json文件默认路径为 appdata 下的apps.json见 src/config.cpp 中APPS_JSON_PATH定义。行为注意事项Windows 上 Sunshine 使用 Desktop Duplication API仅能捕获用于显示的 GPU。若要捕获并编码 eGPU需把显示器或 HDMI 假负载连接到 eGPU并让游戏运行在该显示器上启动新应用时正在运行的旧应用会被终止任何 prep-commands 失败都会中止应用启动应用退出时串流也会随之结束——例如把steam配成普通cmd而非detached会导致串流立即失败因为 Steam 进程的执行方式会立刻结束detached应用不受此限制Desktop 应用与其他应用行为一致只是没有启动命令它直接开始串流。若误删新建一个名为 Desktop、图片路径为 desktop.png 的应用即可恢复Linux Flatpak 下命令必须以flatpak-spawn --host前缀执行连接后输入鼠标、键盘、手柄无效时FreeBSD/Linux 上把运行 sunshine 的用户加入input组FreeBSD 版本缺少 Linux 上的部分特性已知限制仅支持 X11 与 Wayland 捕获手柄走 libvirtualhid 的 uinput 后端运动、触控板输入、电池状态、RGB LED、自适应扳机、原始 HID 输出报告等描述符驱动特性不可用。HDR 支持Windows 主机上正式支持HDR 串流Linux 主机上为实验性支持。通用要求主机操作系统必须已激活 HDR可能需要 HDR 显示器或 EDID 模拟器 dongleMoonlight 客户端设置中也必须开启 HDR否则串流为 SDR主机处于 HDR 时可能过曝良好体验依赖主机与客户端两侧的正确 HDR 校准两者可能差异显著可能需要在游戏内调节亮度滑杆或 HDR 校准选项以适配客户端显示器的亮度能力部分 GPU 视频编码器在 HDR 下的画质或编码性能可能低于 SDR。平台细节Windows支持能编码 HEVC Main 10 或 AV1 10-bit 档位的 Intel、AMD、NVIDIA GPU。建议通过串流 Windows HDR Calibration 应用到客户端完成显示器校准并保存校准配置文件使用 NVIDIA 私有 NVAPI HDR而非原生 Windows HDR的旧游戏可能无法正常显示 HDR。Linux支持通过 VAAPI 编码 HEVC Main 10 或 AV1 10-bit 档位的 Intel 与 AMD GPU必须使用 KMS 捕获后端NvFBC、X11 等不支持 HDR需要支持 HDR 渲染的桌面合成器如 Gamescope 或 KDE Plasma 6。教程与指南官方维护的进阶指南见 docs/guides.md社区生成的教程与指南内容可在该文档的指引下列出教程与指南均为社区贡献内容。完整的配置项参考见 docs/configuration.md版本变更历史见 docs/changelog.md。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考