Sunshine 虚拟手柄配置教程：从接入到按键映射的完整流程

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

Sunshine 是 Moonlight 配套的自托管游戏串流主机，本文讲清它的虚拟手柄（把客户端手柄"变成"主机上的一个真实设备）如何配置、如何按场景调参，以及 Windows / Linux / macOS 三平台的差异。适合刚跑通串流、想把手柄用顺手的用户；已有基础的用户可直接跳到分场景进阶部分。

虚拟手柄的工作原理与数据流

传统远程方案里，游戏只能看到"远程传来的按键事件"，很多游戏因此识别不到手柄。Sunshine 的做法是在主机上创建一个虚拟设备：客户端 Moonlight 把手柄状态包通过 RTSP 通道发过来，Sunshine 解码后写入系统底层驱动（Linux 的uinput/uhid，Windows/macOS 的 HID 驱动），于是主机上出现一个"物理存在"的虚拟手柄，游戏按本地手柄处理。

理解这张图的关键只有一个点：gamepad配置项决定了仿真类型。默认auto时按客户端上报的手柄类型自动选择；类型未知时，若客户端支持触摸板或运动传感器则倾向于 PlayStation 风格，否则用 Xbox 风格。可选值：generic、ds4、ds5、switch、x360、xone、xseries。

三步完成基础配置

以下是最小可行路径，配置文件位置：Linux/macOS 为~/.config/sunshine，Windows 为%ProgramFiles%\Sunshine\config。

1. 开启手柄输入。配置文件的input段中，controller = enabled表示接受客户端手柄事件。Web UI 的Configuration > Input里对应 "Enable Gamepad Input" 开关。

2. 选择仿真类型。不确定就用auto；游戏只认某类手柄时手动指定。示例：

   [input] controller = enabled gamepad = auto

3. 按平台补齐权限（见下方"平台差异"），然后重启 Sunshine 服务，重新连接 Moonlight 会话——虚拟手柄节点是每次会话重建的，改完配置必须重连客户端。

验证方式：主机上看设备管理器（Windows）或evtest /dev/input/eventX（Linux）里是否出现Sunshine (libvirtualhid)命名的新输入设备。

分场景进阶

键盘与键位相关的调参

手柄之外的输入体验也在这几个参数上：

• key_repeat_delay（默认500）：按键长按多久后开始重复，单位毫秒。改小让重复来得更快。
• key_repeat_frequency（默认24.9）：每秒重复次数，支持小数。
• always_send_scancodes（仅 Windows）：改用扫描码发送按键，兼容性更好，但非美式键盘布局的客户端可能出错。键盘完全无响应时开它，键位错乱时关它。
• key_rightalt_to_key_win（默认disabled，仅 Windows）：把右 Alt 当 Win 键转发。某些 Moonlight 客户端发不出 Win 键时很有用。
• high_resolution_scrolling：启用高精度滚轮滚动，适合在主机上用触屏滚轮的客户端。

[input] key_repeat_delay = 400 key_repeat_frequency = 27 key_rightalt_to_key_win = enabled

用 Back 键模拟 Home 键

部分游戏（尤其是从模拟器或主机移植的作品）用 Home/Guide 键返回菜单。Sunshine 提供back_button_timeout（默认-1）：长按 Select/Back 达到该毫秒数就模拟一次 Home 键按下；设为负数则完全不模拟。

[input] back_button_timeout = 2000

另外两个开关控制 PlayStation 风格手柄的附加特性：ds4_back_as_touchpad_click（Back 键兼作触摸板点击）和motion_as_ds4/touchpad_as_ds4（客户端上报运动/触摸板时是否纳入手柄类型自动判断）。对需要触摸板点击才能暂停游戏的客户端，开启ds4_back_as_touchpad_click后无需物理触摸板。

本地多人游戏：一台主机多个手柄

Sunshine 的输入层最多跟踪 16 个手柄槽位（MAX_GAMEPADS），每个串流客户端占用若干槽位，多人本地游戏时每个客户端手柄会自动落到独立槽位，无需手动分配。需要注意两点：

• 客户端数量和手柄总数别超槽位上限，超出的手柄不会出现。
• 应用级配置里可以针对某个 app 单独限定输入行为，例如限定只启用某类手柄类型，避免不同 app 之间互相干扰。

降低输入延迟的参数方向

输入链路本身的延迟主要取决于网络和主机驱动注入速度，可调项有限：

• 主机端：主机与客户端尽量同网段；Linux 下确保 Sunshine 有input组权限，走uinput路径而不是反复申请权限。
• 编码端：串流延迟的大头其实在视频编码。用硬件编码器（nvenc/vaapi/videotoolbox等）并把bitrate、fps按带宽设置，输入体感会明显改善。
• 客户端：Moonlight 侧的缓冲设置调小，牺牲一点抗抖动能力换更低延迟。

平台差异：Windows / Linux / macOS

Linux 侧 udev 规则随安装包自带（见 src_assets/linux/misc/60-sunshine.rules），为uinput、uhid和libvirtualhid/uhid/*虚拟设备统一授权到input组。若重装或权限异常，重新加载即可：

sudo udevadm control --reload-rules sudo udevadm trigger --subsystem-match=hidraw sudo udevadm trigger --subsystem-match=input

Windows 侧若选择 ViGEmBus 作为兜底后端，安装过程大致如下：

故障排查速查

收尾提醒

1. 所有输入类改动都在客户端重连后生效，虚拟设备按会话创建，这是排查时最先要排除的变量。
2. Windows 上 ViGEmBus 已停止维护，长期建议使用 Virtual HID Broker；macOS 上 Broker 为必装组件，两者都需要许可证才能创建手柄。
3. 细节以官方文档为准：配置文档、故障排查、安装指南；平台输入实现见 src/platform/，虚拟手柄抽象在 src/platform/virtualhid_input.cpp。

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