Sunshine 串流故障排查手册从 Linux 输入、网络丢包到 Windows 手柄与 Raw Input 的完整排障指南【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine本文是 Sunshine面向 Moonlight 客户端的自托管游戏串流主机的实战排障指南完整覆盖 docs/troubleshooting.md 中关于凭据恢复、虚拟输入、网络丢包、编码器降帧、KMS/Portal 捕获及多平台输入驱动的全部议题并结合仓库源码CLI 参数注册、EGL 上下文创建、端口分配、udev 规则与 Web UI 排查页逐项剖析根因。读完你可以根据日志关键字快速定位故障类别并按给出的命令序列与推荐配置完成修复。写在前面故障排查的通用入口先看日志再看 Web UI 的 Troubleshooting 页Sunshine 默认将日志写入用户数据目录下的sunshine.log见 src/config.cpp 中的默认配置默认端口基值为47989Web UIHTTPS位于端口47990参考 src/config.cpp 与 src/entry_handler.cpp。出现问题时打开https://localhost:47990登录 Web UI在导航栏进入Troubleshooting页面逐条展开其中的警告warning/错误error信息按日志定位根因Web UI 的 Troubleshooting 页也集中呈现虚拟输入驱动与许可证状态Windows 下见 src_assets/common/assets/web/troubleshooting.html需要更详细级别时可用命令行参数覆盖日志级别sunshine --help中列出的配置项均可通过namevalue方式在命令行覆盖见 src/logging.cpp。忘记 Web UI 凭据怎么办--creds重置Web UI 首次启动时要求你设置用户名与密码。若遗忘无需重装直接通过命令行重置通用安装源码/原生包直接执行二进制sunshine --creds {new-username} {new-password}AppImage./sunshine.AppImage --creds {new-username} {new-password}Flatpakflatpak run --commandsunshine dev.lizardbyte.app.Sunshine --creds {new-username} {new-password}[!TIP] 请务必将{new-username}与{new-password}替换为你的新凭据且不要保留花括号本身。这一行为在源码中有清晰的实现链路--creds子命令注册于 src/main.cpp 的命令映射表最终由args::creds()调用http::save_user_creds()将新凭据写入config::sunshine.credentials_filesrc/entry_handler.cpp因此该参数本质上是覆写凭据存储文件的操作重置后即可用新用户名/密码登录 Web UI。顺带说明sunshine --help还会列出-0从 stdin 读取 PIN等标志src/logging.cpp这些在首配与排查时同样有用。鼠标与游戏手柄的输入类故障鼠标行为异常如果客户端出现异常的鼠标行为先在Sunshine 主机端接上一只物理鼠标再行验证。这能快速排除虚拟鼠标注入路径本身失效与客户端输入通道两类不同的原因缩小排查范围。手柄在 Steam 中正常、进游戏却无效一个常见技巧修改 Steam 设置勾选/取消Xbox/PlayStation 配置支持只保留Generic通用手柄支持。另一个思路与手柄排序有关如果主机上已经直连了多只手柄可以临时禁用它们使 Sunshine 提供来自客户端的虚拟手柄成为系统中第一个手柄。在 Linux 上可通过 USB 设备路径实现# 在 /sys/bus/usb/devices/ 下找到目标设备后向其 authorized 文件写入 0 echo 0 | sudo tee /sys/bus/usb/devices/{device}/authorizedLinux装好之后输入完全无效udev 规则未生效Sunshine 通过虚拟 HIDlibvirtualhid/uhid、uinput创建虚拟游戏手柄、键盘、鼠标设备节点。安装完成后需要重载 udev 规则安装后置脚本postinst通常会代为执行但若失败可能需要重启系统。Sunshine 会在每次串流会话时重建虚拟手柄设备节点因此手工chmod/setfacl的设置会在客户端重连后丢失。请确认所安装的规则文件仓库中的模板见 src_assets/linux/misc/60-sunshine.rules同时包含parent-property 导入与libvirtualhid/uhid/*匹配然后按序重载并重新应用到现有手柄节点# 1) 确认规则内容存在IMPORT{parent} 与 libvirtualhid/uhid/* 匹配 grep -R -E IMPORT\{parent\}HID_\*|ENV\{HID_PHYS\}libvirtualhid/uhid/\* \ /etc/udev/rules.d /usr/lib/udev/rules.d /lib/udev/rules.d 2/dev/null # 2) 重载规则 sudo udevadm control --reload-rules # 3) 对 hidraw 与 input 子系统重新触发 sudo udevadm trigger --subsystem-matchhidraw sudo udevadm trigger --subsystem-matchinput若仍无效把运行 Sunshine 的用户加入input组虚拟输入设备节点依赖该组权限sudo usermod -aG input $USER[!NOTE] 修改用户组后需要注销并重新登录或重启才能生效。Linux 多席位Multiseat虚拟设备被注入到错误的 seat当你在独立的 logind seat例如seat0、seat1上运行多个并发的 Wayland 会话时合成器compositor可能忽略注入的输入——除非 Sunshine 的虚拟设备被正确分配到对应 seat。Sunshine 通过XDG_SEAT环境变量确定目标 seat通常由显示管理器自动设置。必要时可以在启动 Sunshine 前于 systemd 服务文件或 shell 环境中手工覆盖该变量。当 seat 不是seat0时Sunshine 会把 seat 名追加到虚拟设备名上例如Keyboard passthrough (seat1)Sunshine (libvirtualhid) PS5 Controller (seat1)注意 Sunshine 会创建两个鼠标设备一个相对鼠标与一个绝对鼠标。要把这些虚拟设备归属到正确 seat可创建如下的 udev 规则文件/etc/udev/rules.d/72-sunshine-virtual-seat.rulesSUBSYSTEMinput, KERNELinput*, ATTR{name}*(seat1)*, TAGseat, ENV{ID_SEAT}seat1然后重载 udev 并触发 input 子系统sudo udevadm control --reload-rules sudo udevadm trigger -s inputWindows检测不到手柄gamepadWindows 平台同样基于 libvirtualhid 实现虚拟输入。要点如下需要单独安装 Virtual HID Driver才能获得基于驱动的 Raw Input 键盘鼠标与完整的虚拟手柄支持当 libvirtualhid 不可用时ViGEmBus 仅作为受限回退方案被识别只支持 Xbox 360 与 DualShock 4 手柄若走该回退方案必须使用1.17 或更新版本Sunshine 要求 Virtual HID Driver 版本2026.905.2300.20 或更新Virtual HID Driver 除 Xbox 360/DualShock 4 外还支持 Xbox One、Xbox Series、DualSense、Nintendo Switch Pro 与 Generic 手柄并在受支持时暴露体感motion、触摸板、LED 与自适应扳机等高级特性与已停止维护的 ViGEmBus 不同该项目由 LizardByte 团队持续开发维护Virtual HID Driver 需要有效的机器许可证Sunshine 才能创建驱动托管的 libvirtualhid 设备包括手柄与 Raw Input 键盘鼠标。激活/购买入口可通过 Web UI 首页的警告横幅、启动时的托盘通知或托盘Virtual HID Driver子菜单进入 Troubleshooting 页的许可证区对应 src_assets/common/assets/web/troubleshooting.html 中的virtualhid-license区块完成安装或更新虚拟输入驱动后建议重启电脑。Windows游戏检测不到键盘输入在 Virtual HID Driver 兼容且许可证有效的前提下Sunshine 会通过真实的 HID 键盘发送普通按键状态转换因此使用Raw Input的游戏可以收到按键。Unicode 文本输入与位于受支持 HID 键盘页keyboard page之外的按键仍走 Windows 输入注入。当驱动、broker 或许可证不可用、无法创建驱动托管键盘时libvirtualhid 会回退到 SendInput。检查项在 Web UI Troubleshooting 页查看 Virtual HID Driver 的版本与许可证状态Sunshine 在许可证激活、验证或注销成功后会重建共享键盘与鼠标因此在 HID 与 SendInput 两种路径间切换无需重启 Sunshine。Windows游戏检测不到鼠标输入机制与键盘一致Virtual HID Driver 兼容且许可证有效时相对鼠标移动、按键与滚轮通过真实 HID 设备送出Raw Input 游戏可收到绝对定位仍使用 Windows 输入注入。驱动托管鼠标创建失败时回退到 SendInput——此时 Windows 光标可能仍在移动但只监听 Raw Input 的游戏收不到任何消息。即使禁用了手柄输入也建议在 Web UI Troubleshooting 页检查 Virtual HID Driver 版本与许可证。键盘与鼠标路径使用相同的实时刷新机制可即时在 HID 与 SendInput 间切换无需重启 Sunshine。Windows启动应用报 Permission deniedSunshine 在 Windows 上以服务身份运行其访问权限可能低于你的普通用户账户。当从非系统盘启动游戏/应用时可能出现权限拒绝错误。解决办法是修改磁盘的安全权限确保SYSTEM用户/主体对该磁盘拥有完全控制权限。网络质量与丢包类故障用 iPerf3 评估网络质量实时游戏串流对服务端与客户端之间网络路径最重要的要求并非纯粹的带宽而是稳定与一致低延迟且波动小、几乎无丢包。推荐的压测工具是跨平台工具iPerf3。在 Sunshine 主机上以服务器模式启动iperf3 -s在客户端设备上发起 60 秒的UDP 反向测试反向 服务器发往客户端并指定目标码率例如 50 Mbpsiperf3 -c {HostIpAddress} -t 60 -u -R -b 50M观察客户端输出中的packet loss与jitter两者都应非常低。理想情况下丢包率低于5%抖动低于1 ms。工具提示Android 客户端可使用PingMaster类网络工具iOS 客户端可使用HE.NET Network Tools。若测试的是跨互联网的远程连接需要在主机上转发端口5201TCP 与 UDP。大流量丢包Buffer overrun / 缓冲区溢出成因当 Sunshine 主机到网络的速度远快于通往客户端路径中最慢的一段时可能出现大规模丢包。Sunshine 每 16 ms对应 60 fps产生一次突发burst数据流但这些突发无法被足够快地转发给客户端只能由链路中的某个网络设备缓冲若码率足够高缓冲区溢出数据被丢弃。典型场景主机 2.5 Gbit/s 接入、客户端仅 1 Gbit/s 或走 Wi-Fi主机 1 Gbps、客户端仅有 100 Mbps 接口。方案 A降低主机网卡速率如 2.5 G 改为 1 Gbps、1 Gbps 改为 100 Mbps。方案 B在操作系统层面做流量整形只对 Sunshine 的流量限速更精细、不影响其他流量。Linux 上可用tc实现例如把 Sunshine 串流限速为 1 Gbit、其余流量保留满速 10 Gbit# 1) 移除现有 qdiscpfifo_fast sudo tc qdisc del dev NIC root # 2) 添加 HTB 根 qdisc默认类别 1:1 sudo tc qdisc add dev NIC root handle 1: htb default 1 # 3) 创建类别 1:1其他所有流量全速 10 Gbit/s sudo tc class add dev NIC parent 1: classid 1:1 htb \ rate 10000mbit ceil 10000mbit burst 32k # 4) 创建类别 1:10Sunshine 游戏串流限速 1 Gbit/s sudo tc class add dev NIC parent 1: classid 1:10 htb \ rate 1000mbit ceil 1000mbit burst 32k # 5) 将 UDP 源端口 47998 的流量归入类别 1:10 sudo tc filter add dev NIC protocol ip parent 1: prio 1 \ u32 match ip protocol 17 0xff \ match ip sport 47998 0xffff flowid 1:10要点与限制上述规则重启后不持久如果你为串流使用了不同的端口需要相应调整最后一条命令。端口 47998 即 Moonlight 串流中 Sunshine 的 UDP 视频流源端口Sunshine 的端口体系以基值 47989 为中心展开RTSP 监听端口由 src/rtsp.h 中的RTSP_SETUP_PORT偏移 21 计算得出Web UI 在基值 1 的 47990Sunshine 0.23.1 版本已包含改进的网络代码有望缓解甚至解决该问题无需降低网卡速率。降低 MTU 的非常规手段虽然可能性不大但某些客户端在使用主机端更低的MTU最大传输单元时表现更好。示例一台 LG 电视在主机 MTU 为 1500 与 1472 时出现 30–60% 丢包而把提供串流的 Linux 网卡 MTU 设为 1428 后丢包降为 0%。其具体作用机理尚不明确因此这只作为最后手段的建议。Linux 专用编码器与捕获类故障高 GPU 负载下硬件编码器降帧/丢帧CAP_SYS_NICE现象依赖 EGL 上下文的捕获方式wlgrab或编码器nvenc、vaapi在配合沙箱化或降权安装的 SunshineFlatpak、AppImage或使用 Portal 捕获运行时可能出现 FPS 下降。原因是这类环境下缺少建立高优先级 EGL 上下文所需的CAP_SYS_NICE进程权限。自查方法在 Sunshine 日志中查找如下消息Warning: EGL: context priority set to HIGH but CAP_SYS_NICE capability is missing这条日志的源码出处见 src/platform/linux/graphics.cppmake_ctx()在创建 EGL 上下文前会尝试通过cap_set_flag/cap_set_proc临时获取CAP_SYS_NICE并在驱动支持EGL_IMG_context_priority时请求EGL_CONTEXT_PRIORITY_HIGH_IMG若提权失败nice_warning true且实际优先级达不到 HIGH就会输出上述警告随后该 capability 被立即清除。解决办法切换到 Vulkan 编码即可解决大部分配置下的问题若你的系统不支持 Vulkan 编码请按下表选择推荐配置桌面环境是否支持 Vulkan推荐的 Sunshine 安装类型推荐的捕获与编码配置KDE Plasma是任意portal或kwin捕获 vulkan编码KDE Plasma否非沙箱安装kwin捕获 vaapi/nvenc编码GNOME / 其他是任意portal捕获 vulkan编码GNOME / 其他否非沙箱安装kms捕获 vaapi/nvenc编码硬件编码失败h264_vaapi: Function not implemented出于法律顾虑Mesa 默认禁用了硬件解码与硬件编码。若 Sunshine 日志中出现Error: Could not open codec [h264_vaapi]: Function not implemented可能需要手动编译 Mesa参阅官方 Mesa3D 文档的 Compiling and Installing 章节。必须重新启用被禁用的编码器编译时向构建系统传入以下参数如需解码器可一并启用但解码器对 Sunshine 并非必需此处不展开-Dvideo-codecsh264enc,h265enc其他构建选项可查阅 Mesa 源码树中的meson_options.txt。Portal 捕获的 token 失效Portal 捕获要求你在主机上通过屏幕弹窗手动批准远程桌面Remote Desktop权限由此生成一个 portal token用于后续重连时自动重新授权。但在特定情形下Sunshine 崩溃、切换到其他桌面环境、或发生显示器热插拔事件token 可能丢失或失效从而需要重新手动批准捕获权限。KDE Plasma 用户可以通过切换到kwin捕获绕过该问题也可以执行以下配置为 Sunshine 通过 Portal 捕获启用永久捕获授权flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine yes[!NOTE] 尽管该配置经由 Flatpak 下发它对任何受支持的 Sunshine 安装类型均有效。KMS 串流失败需要特权与 Flatpak/AppImage 限制KMS 屏幕捕获需要提权而 Flatpak 与 AppImage 包不允许这种提权。因此若要使用 KMS 捕获必须优先使用发行版原生包格式如可用。KMS 捕获未来将逐步淘汰转而由XDG Portal 捕获对全部包类型可用替代。KDE Plasma 6.5 下 KMS 串流时部分窗口闪烁/消失KWin 的 overlay 支持会干扰 KMS 捕获。截至 KWin 6.5 该特性尚未默认开启但针对未来默认开启的版本可通过专用环境变量将其关闭export KWIN_USE_OVERLAYS0[!NOTE] 禁用 overlays 会降低 KWin 的渲染效率因此建议改用 XDG Portal 捕获。Nvidia GPU 下 KMS 串流黑屏若 KMS 屏幕捕获导致串流画面为黑屏可能需要为 Nvidia 内核模块设置modeset1参数——在内核命令行中加入nvidia_drm.modeset1具体修改方法请查阅你的发行版文档多数情况下通过 GRUB 加载内核并设置命令行参数。AMD 编码延迟偏高Mesa 版本过旧若在 Moonlight 的性能浮层中观察到异常偏高的编码延迟或其剧烈波动你的 Mesa 库可能过旧低于 24.2在高分辨率如 4K下尤为明显。自 Mesa 24.2 起应用可通过设置专用环境变量请求低延迟模式export AMD_DEBUGlowlatencyencSunshine 会自动设置该变量无需任何手动配置。验证方法用amdgpu_top观察VCLK 与 DCLK频率——未启用该编码器调优时两者会剧烈波动启用低延迟编码后只要编码器在使用中两者会保持在高位。Gamescope 兼容性部分用户反馈在 Gamescope 中运行的游戏进行串流时会出现卡顿stuttering。遇到该现象时可结合上文编码器/捕获降帧章节综合排查。macOS 专用DBus 会话错误若收到以下错误Dynamic session lookup supported but failed: launchd did not provide a socket path, verify that org.freedesktop.dbus-session.plist is loaded!执行launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plistWindows 专用串流画面卡顿使用 NVIDIA 显卡时若遇到卡顿尝试在 NVIDIA 控制面板中关闭vsync:fast快速垂直同步。附按日志关键字快速定位问题症状/日志关键字可能根因优先处理路径context priority set to HIGH but CAP_SYS_NICE capability is missing沙箱/降权环境缺少 CAP_SYS_NICE改用 Vulkan 编码或参照推荐配置表Could not open codec [h264_vaapi]: Function not implementedMesa 禁用硬件编解码编译 Mesa 时传-Dvideo-codecsh264enc,h265enc高码率下大流量丢包上游链路突发数据缓冲溢出降低网卡速率或使用tc仅限速 SunshineUDP 47998Web UI 无法登录忘记凭据sunshine --creds user passFlatpak/AppImage 见上文对应形式键盘/鼠标仅在 Raw Input 游戏中失效Windows 虚拟 HID 路径回退检查 Troubleshooting 页的 Virtual HID Driver 版本与许可证相关实现与文档的进一步阅读入口命令行帮助与参数实现、EGL 上下文与 CAP_SYS_NICE 逻辑、Linux udev 规则模板、Web UI Troubleshooting 页Virtual HID Driver 许可证区、安装与初始化指引。需要深入了解其余文档可继续阅读 API 说明 与 构建指南。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sunshine 串流故障排查手册：从 Linux 输入、网络丢包到 Windows 手柄与 Raw Input 的完整排障指南
Sunshine 串流故障排查手册从 Linux 输入、网络丢包到 Windows 手柄与 Raw Input 的完整排障指南【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine本文是 Sunshine面向 Moonlight 客户端的自托管游戏串流主机的实战排障指南完整覆盖 docs/troubleshooting.md 中关于凭据恢复、虚拟输入、网络丢包、编码器降帧、KMS/Portal 捕获及多平台输入驱动的全部议题并结合仓库源码CLI 参数注册、EGL 上下文创建、端口分配、udev 规则与 Web UI 排查页逐项剖析根因。读完你可以根据日志关键字快速定位故障类别并按给出的命令序列与推荐配置完成修复。写在前面故障排查的通用入口先看日志再看 Web UI 的 Troubleshooting 页Sunshine 默认将日志写入用户数据目录下的sunshine.log见 src/config.cpp 中的默认配置默认端口基值为47989Web UIHTTPS位于端口47990参考 src/config.cpp 与 src/entry_handler.cpp。出现问题时打开https://localhost:47990登录 Web UI在导航栏进入Troubleshooting页面逐条展开其中的警告warning/错误error信息按日志定位根因Web UI 的 Troubleshooting 页也集中呈现虚拟输入驱动与许可证状态Windows 下见 src_assets/common/assets/web/troubleshooting.html需要更详细级别时可用命令行参数覆盖日志级别sunshine --help中列出的配置项均可通过namevalue方式在命令行覆盖见 src/logging.cpp。忘记 Web UI 凭据怎么办--creds重置Web UI 首次启动时要求你设置用户名与密码。若遗忘无需重装直接通过命令行重置通用安装源码/原生包直接执行二进制sunshine --creds {new-username} {new-password}AppImage./sunshine.AppImage --creds {new-username} {new-password}Flatpakflatpak run --commandsunshine dev.lizardbyte.app.Sunshine --creds {new-username} {new-password}[!TIP] 请务必将{new-username}与{new-password}替换为你的新凭据且不要保留花括号本身。这一行为在源码中有清晰的实现链路--creds子命令注册于 src/main.cpp 的命令映射表最终由args::creds()调用http::save_user_creds()将新凭据写入config::sunshine.credentials_filesrc/entry_handler.cpp因此该参数本质上是覆写凭据存储文件的操作重置后即可用新用户名/密码登录 Web UI。顺带说明sunshine --help还会列出-0从 stdin 读取 PIN等标志src/logging.cpp这些在首配与排查时同样有用。鼠标与游戏手柄的输入类故障鼠标行为异常如果客户端出现异常的鼠标行为先在Sunshine 主机端接上一只物理鼠标再行验证。这能快速排除虚拟鼠标注入路径本身失效与客户端输入通道两类不同的原因缩小排查范围。手柄在 Steam 中正常、进游戏却无效一个常见技巧修改 Steam 设置勾选/取消Xbox/PlayStation 配置支持只保留Generic通用手柄支持。另一个思路与手柄排序有关如果主机上已经直连了多只手柄可以临时禁用它们使 Sunshine 提供来自客户端的虚拟手柄成为系统中第一个手柄。在 Linux 上可通过 USB 设备路径实现# 在 /sys/bus/usb/devices/ 下找到目标设备后向其 authorized 文件写入 0 echo 0 | sudo tee /sys/bus/usb/devices/{device}/authorizedLinux装好之后输入完全无效udev 规则未生效Sunshine 通过虚拟 HIDlibvirtualhid/uhid、uinput创建虚拟游戏手柄、键盘、鼠标设备节点。安装完成后需要重载 udev 规则安装后置脚本postinst通常会代为执行但若失败可能需要重启系统。Sunshine 会在每次串流会话时重建虚拟手柄设备节点因此手工chmod/setfacl的设置会在客户端重连后丢失。请确认所安装的规则文件仓库中的模板见 src_assets/linux/misc/60-sunshine.rules同时包含parent-property 导入与libvirtualhid/uhid/*匹配然后按序重载并重新应用到现有手柄节点# 1) 确认规则内容存在IMPORT{parent} 与 libvirtualhid/uhid/* 匹配 grep -R -E IMPORT\{parent\}HID_\*|ENV\{HID_PHYS\}libvirtualhid/uhid/\* \ /etc/udev/rules.d /usr/lib/udev/rules.d /lib/udev/rules.d 2/dev/null # 2) 重载规则 sudo udevadm control --reload-rules # 3) 对 hidraw 与 input 子系统重新触发 sudo udevadm trigger --subsystem-matchhidraw sudo udevadm trigger --subsystem-matchinput若仍无效把运行 Sunshine 的用户加入input组虚拟输入设备节点依赖该组权限sudo usermod -aG input $USER[!NOTE] 修改用户组后需要注销并重新登录或重启才能生效。Linux 多席位Multiseat虚拟设备被注入到错误的 seat当你在独立的 logind seat例如seat0、seat1上运行多个并发的 Wayland 会话时合成器compositor可能忽略注入的输入——除非 Sunshine 的虚拟设备被正确分配到对应 seat。Sunshine 通过XDG_SEAT环境变量确定目标 seat通常由显示管理器自动设置。必要时可以在启动 Sunshine 前于 systemd 服务文件或 shell 环境中手工覆盖该变量。当 seat 不是seat0时Sunshine 会把 seat 名追加到虚拟设备名上例如Keyboard passthrough (seat1)Sunshine (libvirtualhid) PS5 Controller (seat1)注意 Sunshine 会创建两个鼠标设备一个相对鼠标与一个绝对鼠标。要把这些虚拟设备归属到正确 seat可创建如下的 udev 规则文件/etc/udev/rules.d/72-sunshine-virtual-seat.rulesSUBSYSTEMinput, KERNELinput*, ATTR{name}*(seat1)*, TAGseat, ENV{ID_SEAT}seat1然后重载 udev 并触发 input 子系统sudo udevadm control --reload-rules sudo udevadm trigger -s inputWindows检测不到手柄gamepadWindows 平台同样基于 libvirtualhid 实现虚拟输入。要点如下需要单独安装 Virtual HID Driver才能获得基于驱动的 Raw Input 键盘鼠标与完整的虚拟手柄支持当 libvirtualhid 不可用时ViGEmBus 仅作为受限回退方案被识别只支持 Xbox 360 与 DualShock 4 手柄若走该回退方案必须使用1.17 或更新版本Sunshine 要求 Virtual HID Driver 版本2026.905.2300.20 或更新Virtual HID Driver 除 Xbox 360/DualShock 4 外还支持 Xbox One、Xbox Series、DualSense、Nintendo Switch Pro 与 Generic 手柄并在受支持时暴露体感motion、触摸板、LED 与自适应扳机等高级特性与已停止维护的 ViGEmBus 不同该项目由 LizardByte 团队持续开发维护Virtual HID Driver 需要有效的机器许可证Sunshine 才能创建驱动托管的 libvirtualhid 设备包括手柄与 Raw Input 键盘鼠标。激活/购买入口可通过 Web UI 首页的警告横幅、启动时的托盘通知或托盘Virtual HID Driver子菜单进入 Troubleshooting 页的许可证区对应 src_assets/common/assets/web/troubleshooting.html 中的virtualhid-license区块完成安装或更新虚拟输入驱动后建议重启电脑。Windows游戏检测不到键盘输入在 Virtual HID Driver 兼容且许可证有效的前提下Sunshine 会通过真实的 HID 键盘发送普通按键状态转换因此使用Raw Input的游戏可以收到按键。Unicode 文本输入与位于受支持 HID 键盘页keyboard page之外的按键仍走 Windows 输入注入。当驱动、broker 或许可证不可用、无法创建驱动托管键盘时libvirtualhid 会回退到 SendInput。检查项在 Web UI Troubleshooting 页查看 Virtual HID Driver 的版本与许可证状态Sunshine 在许可证激活、验证或注销成功后会重建共享键盘与鼠标因此在 HID 与 SendInput 两种路径间切换无需重启 Sunshine。Windows游戏检测不到鼠标输入机制与键盘一致Virtual HID Driver 兼容且许可证有效时相对鼠标移动、按键与滚轮通过真实 HID 设备送出Raw Input 游戏可收到绝对定位仍使用 Windows 输入注入。驱动托管鼠标创建失败时回退到 SendInput——此时 Windows 光标可能仍在移动但只监听 Raw Input 的游戏收不到任何消息。即使禁用了手柄输入也建议在 Web UI Troubleshooting 页检查 Virtual HID Driver 版本与许可证。键盘与鼠标路径使用相同的实时刷新机制可即时在 HID 与 SendInput 间切换无需重启 Sunshine。Windows启动应用报 Permission deniedSunshine 在 Windows 上以服务身份运行其访问权限可能低于你的普通用户账户。当从非系统盘启动游戏/应用时可能出现权限拒绝错误。解决办法是修改磁盘的安全权限确保SYSTEM用户/主体对该磁盘拥有完全控制权限。网络质量与丢包类故障用 iPerf3 评估网络质量实时游戏串流对服务端与客户端之间网络路径最重要的要求并非纯粹的带宽而是稳定与一致低延迟且波动小、几乎无丢包。推荐的压测工具是跨平台工具iPerf3。在 Sunshine 主机上以服务器模式启动iperf3 -s在客户端设备上发起 60 秒的UDP 反向测试反向 服务器发往客户端并指定目标码率例如 50 Mbpsiperf3 -c {HostIpAddress} -t 60 -u -R -b 50M观察客户端输出中的packet loss与jitter两者都应非常低。理想情况下丢包率低于5%抖动低于1 ms。工具提示Android 客户端可使用PingMaster类网络工具iOS 客户端可使用HE.NET Network Tools。若测试的是跨互联网的远程连接需要在主机上转发端口5201TCP 与 UDP。大流量丢包Buffer overrun / 缓冲区溢出成因当 Sunshine 主机到网络的速度远快于通往客户端路径中最慢的一段时可能出现大规模丢包。Sunshine 每 16 ms对应 60 fps产生一次突发burst数据流但这些突发无法被足够快地转发给客户端只能由链路中的某个网络设备缓冲若码率足够高缓冲区溢出数据被丢弃。典型场景主机 2.5 Gbit/s 接入、客户端仅 1 Gbit/s 或走 Wi-Fi主机 1 Gbps、客户端仅有 100 Mbps 接口。方案 A降低主机网卡速率如 2.5 G 改为 1 Gbps、1 Gbps 改为 100 Mbps。方案 B在操作系统层面做流量整形只对 Sunshine 的流量限速更精细、不影响其他流量。Linux 上可用tc实现例如把 Sunshine 串流限速为 1 Gbit、其余流量保留满速 10 Gbit# 1) 移除现有 qdiscpfifo_fast sudo tc qdisc del dev NIC root # 2) 添加 HTB 根 qdisc默认类别 1:1 sudo tc qdisc add dev NIC root handle 1: htb default 1 # 3) 创建类别 1:1其他所有流量全速 10 Gbit/s sudo tc class add dev NIC parent 1: classid 1:1 htb \ rate 10000mbit ceil 10000mbit burst 32k # 4) 创建类别 1:10Sunshine 游戏串流限速 1 Gbit/s sudo tc class add dev NIC parent 1: classid 1:10 htb \ rate 1000mbit ceil 1000mbit burst 32k # 5) 将 UDP 源端口 47998 的流量归入类别 1:10 sudo tc filter add dev NIC protocol ip parent 1: prio 1 \ u32 match ip protocol 17 0xff \ match ip sport 47998 0xffff flowid 1:10要点与限制上述规则重启后不持久如果你为串流使用了不同的端口需要相应调整最后一条命令。端口 47998 即 Moonlight 串流中 Sunshine 的 UDP 视频流源端口Sunshine 的端口体系以基值 47989 为中心展开RTSP 监听端口由 src/rtsp.h 中的RTSP_SETUP_PORT偏移 21 计算得出Web UI 在基值 1 的 47990Sunshine 0.23.1 版本已包含改进的网络代码有望缓解甚至解决该问题无需降低网卡速率。降低 MTU 的非常规手段虽然可能性不大但某些客户端在使用主机端更低的MTU最大传输单元时表现更好。示例一台 LG 电视在主机 MTU 为 1500 与 1472 时出现 30–60% 丢包而把提供串流的 Linux 网卡 MTU 设为 1428 后丢包降为 0%。其具体作用机理尚不明确因此这只作为最后手段的建议。Linux 专用编码器与捕获类故障高 GPU 负载下硬件编码器降帧/丢帧CAP_SYS_NICE现象依赖 EGL 上下文的捕获方式wlgrab或编码器nvenc、vaapi在配合沙箱化或降权安装的 SunshineFlatpak、AppImage或使用 Portal 捕获运行时可能出现 FPS 下降。原因是这类环境下缺少建立高优先级 EGL 上下文所需的CAP_SYS_NICE进程权限。自查方法在 Sunshine 日志中查找如下消息Warning: EGL: context priority set to HIGH but CAP_SYS_NICE capability is missing这条日志的源码出处见 src/platform/linux/graphics.cppmake_ctx()在创建 EGL 上下文前会尝试通过cap_set_flag/cap_set_proc临时获取CAP_SYS_NICE并在驱动支持EGL_IMG_context_priority时请求EGL_CONTEXT_PRIORITY_HIGH_IMG若提权失败nice_warning true且实际优先级达不到 HIGH就会输出上述警告随后该 capability 被立即清除。解决办法切换到 Vulkan 编码即可解决大部分配置下的问题若你的系统不支持 Vulkan 编码请按下表选择推荐配置桌面环境是否支持 Vulkan推荐的 Sunshine 安装类型推荐的捕获与编码配置KDE Plasma是任意portal或kwin捕获 vulkan编码KDE Plasma否非沙箱安装kwin捕获 vaapi/nvenc编码GNOME / 其他是任意portal捕获 vulkan编码GNOME / 其他否非沙箱安装kms捕获 vaapi/nvenc编码硬件编码失败h264_vaapi: Function not implemented出于法律顾虑Mesa 默认禁用了硬件解码与硬件编码。若 Sunshine 日志中出现Error: Could not open codec [h264_vaapi]: Function not implemented可能需要手动编译 Mesa参阅官方 Mesa3D 文档的 Compiling and Installing 章节。必须重新启用被禁用的编码器编译时向构建系统传入以下参数如需解码器可一并启用但解码器对 Sunshine 并非必需此处不展开-Dvideo-codecsh264enc,h265enc其他构建选项可查阅 Mesa 源码树中的meson_options.txt。Portal 捕获的 token 失效Portal 捕获要求你在主机上通过屏幕弹窗手动批准远程桌面Remote Desktop权限由此生成一个 portal token用于后续重连时自动重新授权。但在特定情形下Sunshine 崩溃、切换到其他桌面环境、或发生显示器热插拔事件token 可能丢失或失效从而需要重新手动批准捕获权限。KDE Plasma 用户可以通过切换到kwin捕获绕过该问题也可以执行以下配置为 Sunshine 通过 Portal 捕获启用永久捕获授权flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine yes[!NOTE] 尽管该配置经由 Flatpak 下发它对任何受支持的 Sunshine 安装类型均有效。KMS 串流失败需要特权与 Flatpak/AppImage 限制KMS 屏幕捕获需要提权而 Flatpak 与 AppImage 包不允许这种提权。因此若要使用 KMS 捕获必须优先使用发行版原生包格式如可用。KMS 捕获未来将逐步淘汰转而由XDG Portal 捕获对全部包类型可用替代。KDE Plasma 6.5 下 KMS 串流时部分窗口闪烁/消失KWin 的 overlay 支持会干扰 KMS 捕获。截至 KWin 6.5 该特性尚未默认开启但针对未来默认开启的版本可通过专用环境变量将其关闭export KWIN_USE_OVERLAYS0[!NOTE] 禁用 overlays 会降低 KWin 的渲染效率因此建议改用 XDG Portal 捕获。Nvidia GPU 下 KMS 串流黑屏若 KMS 屏幕捕获导致串流画面为黑屏可能需要为 Nvidia 内核模块设置modeset1参数——在内核命令行中加入nvidia_drm.modeset1具体修改方法请查阅你的发行版文档多数情况下通过 GRUB 加载内核并设置命令行参数。AMD 编码延迟偏高Mesa 版本过旧若在 Moonlight 的性能浮层中观察到异常偏高的编码延迟或其剧烈波动你的 Mesa 库可能过旧低于 24.2在高分辨率如 4K下尤为明显。自 Mesa 24.2 起应用可通过设置专用环境变量请求低延迟模式export AMD_DEBUGlowlatencyencSunshine 会自动设置该变量无需任何手动配置。验证方法用amdgpu_top观察VCLK 与 DCLK频率——未启用该编码器调优时两者会剧烈波动启用低延迟编码后只要编码器在使用中两者会保持在高位。Gamescope 兼容性部分用户反馈在 Gamescope 中运行的游戏进行串流时会出现卡顿stuttering。遇到该现象时可结合上文编码器/捕获降帧章节综合排查。macOS 专用DBus 会话错误若收到以下错误Dynamic session lookup supported but failed: launchd did not provide a socket path, verify that org.freedesktop.dbus-session.plist is loaded!执行launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plistWindows 专用串流画面卡顿使用 NVIDIA 显卡时若遇到卡顿尝试在 NVIDIA 控制面板中关闭vsync:fast快速垂直同步。附按日志关键字快速定位问题症状/日志关键字可能根因优先处理路径context priority set to HIGH but CAP_SYS_NICE capability is missing沙箱/降权环境缺少 CAP_SYS_NICE改用 Vulkan 编码或参照推荐配置表Could not open codec [h264_vaapi]: Function not implementedMesa 禁用硬件编解码编译 Mesa 时传-Dvideo-codecsh264enc,h265enc高码率下大流量丢包上游链路突发数据缓冲溢出降低网卡速率或使用tc仅限速 SunshineUDP 47998Web UI 无法登录忘记凭据sunshine --creds user passFlatpak/AppImage 见上文对应形式键盘/鼠标仅在 Raw Input 游戏中失效Windows 虚拟 HID 路径回退检查 Troubleshooting 页的 Virtual HID Driver 版本与许可证相关实现与文档的进一步阅读入口命令行帮助与参数实现、EGL 上下文与 CAP_SYS_NICE 逻辑、Linux udev 规则模板、Web UI Troubleshooting 页Virtual HID Driver 许可证区、安装与初始化指引。需要深入了解其余文档可继续阅读 API 说明 与 构建指南。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考