企业官网建设流程全解析

Sunshine 虚拟手柄：让手机、平板变成 PC 游戏的物理控制器

【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine

周六晚上，你用平板连着 Moonlight 想玩《艾尔登法环》，游戏却反复提示"未检测到控制器"——手里明明有设备，屏幕上却只有一块触屏。Sunshine 作为自托管游戏串流服务器，内置的虚拟手柄功能专门解决这件事：它把 Moonlight 客户端的触摸、按键和陀螺仪信号，翻译成本机游戏能直接认出的 Xbox 360、DualShock 4 等标准手柄信号。你不需要任何实体手柄，串流目标机上的游戏会以为插着一个真手柄。

它到底在干什么

把虚拟手柄理解成一个"手柄替身"：Moonlight 发来的每一记按键，都被 Sunshine 在宿主机上"代打"成一个标准控制器的动作。游戏不关心你的输入来自屏幕还是橡胶按键，只关心有没有一个合法手柄在响应。

开始之前需要准备什么

• Moonlight 客户端：装在手机、平板或另一台电脑上，是串流的发送端，虚拟手柄的原始输入都从它来。
• 宿主机装好 Sunshine 并以服务方式运行：虚拟手柄由 Sunshine 进程在宿主侧创建，Sunshine 不跑，后面全白搭。
• 按平台装驱动：
  • Windows：官方推荐 Virtual HID Broker（LizardByte 在维护的虚拟输入驱动，支持 Xbox One/Series、DualSense 等全套手柄型号）；免费的 ViGEmBus 只支持 Xbox 360 和 DualShock 4 两种型号，且已停止更新，仅作兜底。
  • macOS：虚拟手柄同样依赖单独安装的 Virtual HID Broker。
  • Linux：需要读写/dev/uinput的权限（虚拟输入设备节点），官方安装脚本会自动建好input组；Web UI 检测缺失时会直接给出修复步骤。
• Web UI 可访问：浏览器打开https://localhost:47990，首次访问需输入初始化时设置的账号密码，忽略自签名证书的警告即可。

把虚拟手柄开起来

Sunshine 现在主要通过 Web UI 配置，界面里的 Input 页就是虚拟手柄的控制台。进去后确认控制器输入是开启状态（默认就是开启的），改完保存，无需重启服务。

Web UI 里的 ViGEmBus 驱动安装入口，Windows 用户的一键安装入口

接着选择手柄后端。Windows 和 macOS 上，Sunshine 未选过后端时会持续弹提示，让你在"全部可用驱动 / 仅 Virtual HID Broker / 仅 ViGEmBus / 禁用"之间挑一个；选"全部"意味着有有效许可证时优先走 Virtual HID Broker，没有就自动退回 ViGEmBus 兜底。Linux 不需要这一步，直接走系统自带的 uinput。

最后是仿真型号。默认auto：Sunshine 根据 Moonlight 上报的控制器类型来选，带运动传感器或触摸板的设备会选 PlayStation 风格手柄，其余默认 Xbox 风格。想固定成某一款就直接指定：

gamepad = x360

x360、xone、xseries、ds4、ds5、switch、generic七个值对应不同型号，完整列表见 配置文件说明。

然后打开 Moonlight，连上你的 Sunshine 主机进游戏。屏幕上的虚拟按键出现、游戏里手柄图标亮起、设备管理器或系统设置里能看到新控制器——看到任意一条，就说明链路通了。

按场景微调

• 玩靠陀螺仪的游戏（射箭、体感类）：保持motion_as_ds4默认开启，客户端上报的运动数据会让 Sunshine 优先仿真 DS4；不需要体感时关掉它，避免误判。
• 客户端有触摸板输入：touchpad_as_ds4默认开启，触摸板会仿真成 DS4 触摸板；游戏把触摸板点击当成别的东西时，可以关掉试试。
• 某款游戏只认特定布局：把gamepad从auto改成对应型号，比如只认 DualShock 4 的游戏改成ds4。注意 ViGEmBus 后端下只有auto、x360、ds4可选，想要更多型号得用 Virtual HID Broker。
• PS 风格手柄里"Select 键"没反应：打开ds4_back_as_touchpad_click，让该按键同时触发 DS4 触摸板点击——不少游戏实际绑定的是这个动作而不是按键本身。
• 按键位置不合手：这属于客户端范畴，直接在 Moonlight 的设置里改控制器布局和按键映射，别去改 Sunshine 配置。
• 在意操作延迟：手柄信号本身是几十字节的 UDP 小包，几乎不产生延迟；你感觉到的延迟九成来自视频编码和网络。调编码参数、换有线网络，见 性能调优。

出了问题往哪查

如果游戏完全检测不到控制器，先别怀疑游戏——打开 Web UI 的故障排除页，看 Virtual Input 一栏的驱动版本和许可证状态；驱动没装好或许可证失效，Sunshine 会连兜底提示都给你弹出来。把驱动装好、重启电脑（装过虚拟输入驱动后官方建议重启），再重连 Moonlight 会话。

如果控制器被认出来了、但某个按键不生效，多半是仿真型号和游戏不匹配：换一个gamepad值重连，或在 PS 风格手柄下打开ds4_back_as_touchpad_click，再观察游戏内的键位提示变化。

如果是 Raw Input 类游戏连键盘鼠标都收不到，而虚拟手柄又正常——查看日志里 libvirtualhid 的版本和回退记录，确认没有静默退到 SendInput 注入路径：

grep -i "libvirtualhid" sunshine.log

串流中按键有延迟但本地操作正常时，几乎可以排除虚拟手柄本身，优先查编码和网络；日志界面能直接看到是编码卡住还是网络抖动：

故障排除页的日志视图，用来定位串流延迟来源

🐛 平台相关的输入故障案例更多，见 故障排查。

接下来还能做什么

虚拟手柄只是 Moonlight 输入链路的一半：客户端侧的按键布局、宏和每游戏配置都在 Moonlight 里做，两端配合才是完整体验。宿主机侧的输入细节（键位转发、ds4_back_as_touchpad_click之类的开关）都集中在 Web UI 的 Input 页和 配置文件说明 的 Input 章节，需要时直接翻那里。

• 手柄信号是极小的 UDP 包，操作延迟基本等于视频串流延迟，先调视频和网络再怀疑手柄。
• gamepad保持auto，游戏挑手柄时再手动指定型号，重连后生效。
• 排查顺序：故障排除页看驱动和许可证 → 换仿真型号 → 查日志。
• 装过或更新过虚拟输入驱动后，重启一次宿主机。

现在连上 Moonlight，按一个键，看看游戏里亮不亮。

【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine