Sunshine 虚拟手柄配置教程从接入到按键映射的完整流程【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/SunshineSunshine 是 Moonlight 配套的自托管游戏串流主机本文讲清它的虚拟手柄把客户端手柄变成主机上的一个真实设备如何配置、如何按场景调参以及 Windows / Linux / macOS 三平台的差异。适合刚跑通串流、想把手柄用顺手的用户已有基础的用户可直接跳到分场景进阶部分。虚拟手柄的工作原理与数据流传统远程方案里游戏只能看到远程传来的按键事件很多游戏因此识别不到手柄。Sunshine 的做法是在主机上创建一个虚拟设备客户端 Moonlight 把手柄状态包通过 RTSP 通道发过来Sunshine 解码后写入系统底层驱动Linux 的uinput/uhidWindows/macOS 的 HID 驱动于是主机上出现一个物理存在的虚拟手柄游戏按本地手柄处理。理解这张图的关键只有一个点gamepad配置项决定了仿真类型。默认auto时按客户端上报的手柄类型自动选择类型未知时若客户端支持触摸板或运动传感器则倾向于 PlayStation 风格否则用 Xbox 风格。可选值generic、ds4、ds5、switch、x360、xone、xseries。三步完成基础配置以下是最小可行路径配置文件位置Linux/macOS 为~/.config/sunshineWindows 为%ProgramFiles%\Sunshine\config。开启手柄输入。配置文件的input段中controller enabled表示接受客户端手柄事件。Web UI 的Configuration Input里对应 Enable Gamepad Input 开关。选择仿真类型。不确定就用auto游戏只认某类手柄时手动指定。示例[input] controller enabled gamepad auto按平台补齐权限见下方平台差异然后重启 Sunshine 服务重新连接 Moonlight 会话——虚拟手柄节点是每次会话重建的改完配置必须重连客户端。验证方式主机上看设备管理器Windows或evtest /dev/input/eventXLinux里是否出现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_clickBack 键兼作触摸板点击和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对比项WindowsLinuxmacOS虚拟手柄后端Virtual HID Broker付费全功能或 ViGEmBus免费仅x360/ds4已停止维护内核uinput/uhid免费Virtual HID Broker付费gamepad_driver选项all/virtualhid/vigembus/none不适用未设置时用 Virtual HID Broker可选none禁用权限要点安装/更新驱动后建议重启系统Broker 需要机器许可证用户加入input组/dev/uinput读写权限屏幕录制 辅助功能权限Broker 需在设备控制与数据访问中放行特殊行为always_send_scancodes等键位项仅在此平台生效udev 规则为每次会话重建的手柄节点授权改chmod会失效Moonlight 不转发 Command 键右 Option 被映射为 CMD配置路径%ProgramFiles%\Sunshine\config~/.config/sunshine~/.config/sunshineLinux 侧 udev 规则随安装包自带见 src_assets/linux/misc/60-sunshine.rules为uinput、uhid和libvirtualhid/uhid/*虚拟设备统一授权到input组。若重装或权限异常重新加载即可sudo udevadm control --reload-rules sudo udevadm trigger --subsystem-matchhidraw sudo udevadm trigger --subsystem-matchinputWindows 侧若选择 ViGEmBus 作为兜底后端安装过程大致如下故障排查速查现象可能原因处理办法主机上看不到虚拟手柄平台权限缺失Linux 未入input组 / Windows 未装驱动或 Broker 无许可证 / macOS 未放行 Broker按平台差异表补齐权限Web UI 的Troubleshooting页会列出缺失项处理后重启服务并重连客户端手柄出现但游戏只认另一类型gamepad auto判断结果不符合游戏要求手动固定类型如gamepad x360或ds4Windows 用 ViGEmBus 时只有auto/x360/ds4可选Linux 下手柄时灵时不灵、断线重连后消失虚拟手柄节点每次会话重建手动chmod/setfacl被覆盖确认 udev 规则含IMPORT{parent}HID_*与libvirtualhid/uhid/*匹配执行上面两条udevadm命令键盘在部分游戏无响应或按键错乱Windows扫描码与虚拟键码路径不匹配错乱就关always_send_scancodes完全无响应就开它改完配置无效果虚拟手柄节点未在旧会话更新断开并重新连接 Moonlight 会话必要时重启 Sunshine 服务收尾提醒所有输入类改动都在客户端重连后生效虚拟设备按会话创建这是排查时最先要排除的变量。Windows 上 ViGEmBus 已停止维护长期建议使用 Virtual HID BrokermacOS 上 Broker 为必装组件两者都需要许可证才能创建手柄。细节以官方文档为准配置文档、故障排查、安装指南平台输入实现见 src/platform/虚拟手柄抽象在 src/platform/virtualhid_input.cpp。【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
