Sunshine 虚拟手柄配置指南：3 项检查加 1 份最小配置，串流 PC 游戏
【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine
Sunshine 是自托管游戏串流服务器，为 Moonlight 客户端提供串流服务。它的虚拟手柄功能可以把手机、平板的触摸与陀螺仪输入，转换为主机系统能识别的标准手柄信号。本文解决四个问题：虚拟手柄驱动要求、最小配置写法、手柄类型选择，以及延迟调优与常见故障排查。
先搞清楚它做了什么
信号流向很短：Moonlight 客户端采集屏幕上的虚拟按键、陀螺仪等输入，通过串流通道发给 Sunshine；Sunshine 把这些输入转换为主机系统能识别的标准手柄信号（虚拟手柄设备），游戏收到的就是一只普通手柄。换句话说，游戏不需要知道输入来自手机。
配置前检查清单
动手改配置之前，逐项确认以下条件：
| 检查项 | 要求 |
|---|---|
| 操作系统 | Windows 10/11，或主流 Linux 发行版 |
| 虚拟手柄驱动 | Windows 需安装 ViGEmBus，版本 1.17 及以上 |
| 驱动安装入口 | Sunshine Web 界面「故障排除」页可直接一键安装 |
| Sunshine 服务 | 服务进程正常运行，Web 界面可访问 |
| 客户端 | 手机或平板已安装 Moonlight，且能发现主机 |
| 网络 | 客户端与主机可互通，同网段优先 |
最小可运行配置
配置只写两个字段就能跑通。Windows 配置文件位于%APPDATA%\sunshine\，Linux 位于~/.config/sunshine\，格式为 INI：
[input] controller = enabled gamepad = autocontroller = enabled：允许客户端发送手柄输入，默认是禁用的，这是虚拟手柄不生效的头号原因。gamepad = auto：由 Sunshine 根据客户端上报的设备类型自动选择要模拟的手柄。
改完保存，重启 Sunshine 服务后，用 Moonlight 重新发起串流即可看到屏幕上的虚拟手柄界面。
手柄类型怎么选：自动 vs 手动
先说自动模式的判定规则：客户端上报了已知手柄类型时直接采用；类型未知时，设备带陀螺仪或触摸板就选 PlayStation 系，否则选 Xbox 系。大多数设备停留在auto就够了，按下表处理特殊情况：
| 设备特征 | 推荐类型 | 适用场景 |
|---|---|---|
| 类型无法识别、带陀螺仪或触摸板 | ds4 | 兼容 PS 系手柄的游戏 |
| 类型无法识别、无上述特征 | x360 | 兼容性最广的默认选择 |
| 游戏只认指定手柄类型 | 手动指定 ds4、ds5、x360、xone、switch、generic | 自动选择结果不满足时 |
注意：Windows 上使用 ViGEmBus 驱动时，gamepad只支持auto、x360、ds4三个取值，驱动版本 1.17 以上。
手动指定的写法，直接替换auto：
[input] controller = enabled gamepad = x360保存并重启服务后生效。
把延迟降下来：参数与网络调优
输入延迟和画面延迟由两套因素决定：串流参数、网络质量。按下表调整：
[stream] fps = 60 bitrate = 15000| 参数 | 推荐值 | 说明 |
|---|---|---|
fps | 60 | 客户端性能不足或网络较差时降到 30 |
bitrate | 15000（kbps） | 出现丢帧、马赛克时降到 10000–15000 |
packet_size | 1024 | 跨网段传输时可适当调大 |
网络侧三条原则：
- 优先有线；无线用 5 GHz 频段。
- 路由器开启 QoS，为串流流量预留带宽。
- 关闭其他设备的占带宽应用。
局域网内还可用 UPnP 简化端口转发，在 Web 界面 Configuration 页搜索Upnp即可开启：
出问题了：故障速查表
遇到异常时，先开 debug 日志再对照下表：
[general] min_log_level = debug| 现象 | 最可能原因 | 处理动作 |
|---|---|---|
| 虚拟手柄无响应 | ViGEmBus 未装好；controller仍为禁用；权限不足 | 重装驱动（管理员权限）；配置页确认controller = enabled；Linux 确认/dev/uinput读写权限 |
| 按键映射错误 | 自动选错手柄类型；游戏使用非标准布局 | 手动指定gamepad；在 Moonlight 里建自定义布局；检查游戏内手柄设置 |
| 延迟明显 | 带宽不足；编码参数过高；客户端性能不足 | bitrate降到 10000–15000；fps降到 30；改用有线网络 |
| 个别游戏不识别 | 游戏要求特定手柄类型；防作弊拦截虚拟输入 | 换x360、ds4等类型逐一尝试；确认 Sunshine 权限不低于游戏进程 |
不同平台的差异要点
Windows 服务端：
- 虚拟手柄依赖 ViGEmBus，Web 界面「故障排除」页可一键安装；
- 检查 Windows Defender 是否拦截了 Sunshine 进程；
- 以管理员权限运行的游戏，需要 Sunshine 拥有不低于游戏的输入权限；
- 显卡驱动保持更新，降低编码异常导致的卡顿。
Linux 服务端最小必要命令，把用户加入 input 组并写入 udev 规则：
sudo usermod -aG input $USER echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-sunshine-input.rules sudo udevadm control --reload-rules执行后重新登录，虚拟手柄输入才能获得/dev/uinput的读写权限。
客户端侧：
- 触摸板布局在 Moonlight 里配置，按游戏单独保存；
- 陀螺仪类输入仅在设备支持且手柄类型为 ds4/ds5 时可用；
- 平板与主机之间保持低延迟网络，输入体验才稳定。
完整的配置项清单以官方文档docs/configuration.md为准，遇到驱动版本或特殊设备问题可以到项目社区提问。
【免费下载链接】SunshineSelf-hosted game stream host for Moonlight.项目地址: https://gitcode.com/GitHub_Trending/su/Sunshine
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
