如何配置 Sunshine 虚拟手柄3 步完成从驱动到首次连接的完整设置【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine本文基于 SunshineMoonlight 的自托管游戏串流服务器讲解虚拟手柄Virtual Gamepad功能它让 Moonlight 客户端上的屏幕按键被宿主机识别为标准游戏手柄信号适用于没有物理手柄、或希望用手机/平板直接操作 PC 与 Linux 游戏的用户。内容覆盖驱动自检、首次连接流程、按场景调优和故障速查。虚拟手柄如何工作虚拟手柄的信号转换链路只有四步Moonlight 客户端把屏幕上的虚拟按键、摇杆、陀螺仪输入编码后发给 Sunshine 服务Sunshine 通过 libvirtualhid 库在宿主机上创建一个虚拟手柄设备Windows 走 Virtual HID Broker 或 ViGEmBus 驱动Linux/FreeBSD 走/dev/uinput操作系统把该设备当成普通物理手柄枚举游戏按标准 XInput/HID 手柄读取输入与接真实手柄无异。关键点输入注入发生在宿主机本地所以手柄本身的延迟极低感知到的延迟主要来自视频链路。自动模式下Sunshine 会根据客户端上报的控制器类型选择模拟设备——客户端报告有陀螺仪或触摸板时选 PlayStation 风格如 ds4否则选 Xbox 风格。准备自检开始前的前置条件按表逐项确认全部通过后再开始首次连接。检查项检查方法通过标准Sunshine 服务在运行Linux 执行systemctl --user status app-dev.lizardbyte.app.SunshineWindows 在“服务”中查看 Sunshine 状态状态为 active / Running手柄输入已启用Web UI 的 Configuration Input 中 Enable Gamepad Input 为开启配置文件项为controller enabled开关处于 enabled宿主机虚拟手柄驱动就绪Windows安装 ViGEmBus≥1.17或激活 Virtual HID Broker 机器授权LinuxWeb UI Troubleshooting Permissions 查看/dev/uinput权限Windows 无驱动缺失提示Linux 无权限缺失提示客户端就绪Moonlight 已安装且与宿主机在同一网络Moonlight 能搜到宿主主机名Web 管理界面可访问浏览器打开https://localhost:47990能看到登录页自签名证书警告属正常现象直接继续首次连接从启动到手柄被识别打开 Web 管理界面https://localhost:47990登录。确认导航栏无红色告警。在 Configuration Input 中保持 Enable Gamepad Input 开启模拟类型gamepad先用默认值auto。添加串流目标在应用管理页加入 Desktop 或某个游戏。验证新目标出现在应用列表中点击可正常启动。 4. 在 Moonlight 中搜索并选中宿主机。Moonlight 提示配对时回到 Web 管理界面导航栏的 PIN 处输入 PIN 回车并给设备命名。 验证Moonlight 显示配对成功宿主机出现在已配对设备列表。 5. 开始串流在 Moonlight 的屏幕虚拟手柄上按 A/B/摇杆。 验证游戏内对应按键生效Windows 设备管理器中能看到新枚举的虚拟控制器Web UI Troubleshooting 页无[libvirtualhid]前缀的报错。成功判定标准游戏内虚拟按键有响应且 Troubleshooting 日志中无虚拟手柄相关的驱动或授权错误。 按场景调优手动指定模拟手柄类型解决游戏不识别auto选错时在配置文件Linux 路径~/.config/sunshineWindows 路径%ProgramFiles%\Sunshine\config中显式指定然后重连 Moonlight 会话# 可选值auto / generic / ds4 / ds5 / switch / x360 / xone / xseries gamepad ds4注意Windows 上使用 ViGEmBus 后端时只有auto、x360、ds4可用ds5、switch、xone、xseries、generic需要 Virtual HID Broker 后端。另外ds4_back_as_touchpad_click enabled默认开启会让 Select/Back 键同时触发 PS 风格触摸板点击部分游戏需要此行为遇到异常可改为disabled。排查串流延迟虚拟手柄信号本地注入、延迟极低感知延迟基本来自视频链路和网络用iperf3实测宿主机运行iperf3 -s客户端运行iperf3 -c 宿主机IP -t 60 -u -R -b 50M看丢包与抖动理想值丢包低于 5%、抖动低于 1 ms。若日志出现 Buffer overrun丢包通常是宿主机上行带宽远高于链路最慢段例如宿主机 2.5G 有线对端只有 Wi-Fi降低视频比特率即可缓解。客户端使用 5GHz Wi-Fi 或有线路由器开启 QoS 优先串流流量。调整自动选择行为陀螺仪/触摸板仅当gamepad auto时生效的两项开关motion_as_ds4 enabled默认客户端手柄上报陀螺仪时模拟为 PlayStation 风格手柄不需要陀螺仪时置为disabled。touchpad_as_ds4 enabled默认客户端上报触摸板时模拟 PlayStation 风格手柄同理可关闭。故障速查现象最可能原因处理动作Windows 游戏完全检测不到手柄ViGEmBus 未装或版本过旧或 Virtual HID Broker 授权未激活到 Troubleshooting 页查看 Virtual Input 状态安装/升级驱动或激活授权装完驱动重启电脑手柄在 Steam 里正常、进游戏失效Steam 手柄映射拦截了输入或宿主机插着物理手柄抢了“第一个手柄”位置Steam 设置中仅保留 Generic 控制器支持临时禁用物理手柄让 Sunshine 虚拟手柄排在首位Linux 上键鼠和手柄全部无响应运行 Sunshine 的用户不在input组无/dev/uinput写权限执行sudo usermod -aG input $USER注销后重新登录组权限需新会话生效游戏里鼠标/键盘无响应但光标能动Windows驱动路径未生效回退到 SendInput 注入Raw Input 游戏收不到检查 Troubleshooting 页的 libvirtualhid 驱动版本与 Broker 授权状态延迟高、画面卡顿网络丢包或抖动超限用iperf3复测降低比特率改有线日志中出现[libvirtualhid]前缀错误虚拟手柄设备创建失败按日志逐条核对驱动、授权、权限详见 官方故障排查文档平台差异Windows / Linux / macOS 一次说清Windows提供两个虚拟手柄后端。Virtual HID Brokerlibvirtualhid 的付费组件要求版本2026.914.1218.10以上并激活机器授权支持全部手柄类型及陀螺仪、触摸板、自适应扳机等特性ViGEmBus 免费但已停止维护end of life仅支持 x360 和 ds4版本需 1.17 以上。gamepad_driver配置项控制后端选择all优先 Broker失效回退 ViGEmBus、virtualhid、vigembus、none。安装或更新虚拟输入驱动后建议重启电脑。Linux / FreeBSD虚拟手柄走/dev/uinput安装包会自动创建input组并配置权限若权限缺失把当前用户加入input组即可FreeBSD 用pw groupmod input -m $USER然后注销重登。服务默认名为app-dev.lizardbyte.app.Sunshine别名sunshine.service# 确认服务状态 systemctl --user status app-dev.lizardbyte.app.Sunshine # 补权限执行后需注销并重新登录 sudo usermod -aG input $USERmacOS虚拟手柄必须单独安装 Virtual HID Broker官方 DMG 中的Install libvirtualhid.command并在“系统设置 隐私与安全性 设备控制”中放行/Applications/VirtualHIDBroker.app再在 Sunshine 的 Troubleshooting 页激活机器授权。键盘鼠标走系统标准的合成输入权限路径不受影响。更多细节可参考仓库内文档快速上手 与 完整配置项参考。小结先跑通“驱动 权限 服务”三件套用 Troubleshooting 页核对再动gamepad等高级项auto覆盖大多数场景只有游戏不认时才手动固定类型。遇到异常优先看[libvirtualhid]日志关键词按现象查上表处理细节见官方文档 docs/troubleshooting.md 及 LizardByte 社区。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考