1. 为什么我放弃了 vJoy 转向 Linux 原生手柄调试
在 Linux 上折腾虚拟手柄，很多人第一反应是找 vJoy 这类工具。但 vJoy 本质上是 Windows 平台的产物，在 Linux 环境下要么跑不起来，要么需要套一层兼容层，配置链路长、依赖多、出问题还不好排查。我最初也是从这条路走过来的，踩了不少坑之后才意识到：Linux 内核本身对输入设备（input device）的支持已经非常完善，完全没必要绕远路。
jstest-gtk就是我在这个过程中找到的一个轻量级调试工具。它做的事情很纯粹——把内核识别到的 joystick 设备（包括物理手柄和虚拟手柄）以图形化方式展示出来，让你实时看到每个轴、每个按键的数值变化。整个安装包体积极小，依赖关系简单，从安装到看到界面通常不超过三分钟。
这篇文章适合几类人看：一是在 Linux 上做游戏开发或模拟器配置，需要验证虚拟手柄映射是否正确的开发者；二是用树莓派、香橙派等开发板接手柄做机器人遥控、无人机地面站调试的硬件玩家；三是单纯想在 Linux 上用手柄玩游戏，但不确定系统有没有正确识别设备的普通用户。不管你属于哪一类，只要涉及“Linux 下手柄能不能用、按键对不对”这个问题，jstest-gtk 都能帮你快速定位。
需要提前说明的是，本文讨论的是 Linux 系统下通过内核 uinput 模块创建的虚拟手柄设备，以及如何用 jstest-gtk 验证其配置。整个过程不涉及任何网络代理或跨平台穿透工具，纯粹是本地设备调试。
2. 虚拟手柄在 Linux 下的工作原理与方案选型
2.1 Linux 输入子系统的基本架构
要理解虚拟手柄怎么调试，得先搞清楚 Linux 是怎么处理输入设备的。Linux 内核有一套统一的输入子系统（Input Subsystem），所有输入设备——键盘、鼠标、手柄、触摸屏——都通过这套框架向用户空间上报事件。具体来说，内核中的输入设备驱动收到硬件信号后，会生成input_event结构体，然后通过/dev/input/eventX这样的字符设备节点暴露给用户空间。
手柄类设备比较特殊，它除了走通用的 event 接口，还会注册为 joystick 设备，对应/dev/input/jsX节点。jstest-gtk读的就是jsX这个接口。这个接口的好处是数据格式更贴合手柄的语义——轴值、按键状态都是直接可读的，不需要你自己去解析原始事件流。
虚拟手柄的实现思路就是反过来：在用户空间创建一个程序，通过/dev/uinput这个接口向内核注册一个虚拟的输入设备。内核收到注册请求后，会像对待真实硬件一样，为这个虚拟设备创建对应的eventX和jsX节点。之后你的程序往 uinput 写入事件，内核就会把这些事件分发给所有监听该设备的应用程序。
2.2 为什么选 jstest-gtk 而不是其他工具
市面上能查看手柄输入的工具不止一个，我选 jstest-gtk 有几个实际考量。
evtest是最底层的工具，直接读/dev/input/eventX，输出的是原始事件码和值。它的优点是信息最全，缺点是太底层了——你得自己知道每个事件码对应哪个轴、哪个按键，调试效率低。jstest命令行版比 evtest 好一些，直接显示轴和按键的编号与数值，但没有图形界面，多轴同时变化时看起来费劲。
jstest-gtk在jstest的基础上加了 GTK 图形界面，每个轴用滑块显示，每个按键用指示灯显示，哪个轴在动、哪个键按下了一目了然。而且它支持设备热插拔刷新，虚拟手柄创建后点一下刷新就能看到，不用重启工具。对于快速验证配置这个场景来说，它的效率是最高的。
还有一个实际因素：jstest-gtk 在主流发行版的软件源里都有打包，apt install jstest-gtk或者dnf install jstest-gtk就能装上，不需要自己编译。对于需要快速搭建调试环境的情况，这一点很关键。
2.3 虚拟手柄的典型应用场景
虚拟手柄在 Linux 下有几个高频使用场景。一是游戏模拟器，比如 RetroArch 这类前端，有时候需要把键盘按键映射成手柄输入，虚拟手柄就是中间桥梁。二是自动化测试，比如你要测试一个游戏对手柄输入的处理逻辑，不可能每次都手动操作物理手柄，用虚拟手柄脚本可以精确控制输入序列。三是远程控制场景，比如通过串口或网络收到控制指令后，在本地生成手柄事件来驱动游戏或应用。
这些场景的共同需求是：虚拟手柄创建后，必须能快速验证它是否被系统正确识别、轴和按键映射是否符合预期。jstest-gtk 就是干这个的。
3. 三分钟完成 jstest-gtk 安装与虚拟手柄验证
3.1 安装 jstest-gtk 与依赖检查
在 Debian/Ubuntu 系上，安装命令很直接：
sudo apt update sudo apt install jstest-gtkFedora/RHEL 系：
sudo dnf install jstest-gtkArch 系：
sudo pacman -S jstest-gtk装完之后先别急着打开，确认一下系统有没有识别到 joystick 设备节点：
ls -l /dev/input/js*如果输出类似crw-rw-r-- 1 root input 13, 0 ... /dev/input/js0，说明至少有一个手柄设备被识别了。如果什么都没有，要么是没接物理手柄，要么是虚拟手柄还没创建。
这里有个权限问题需要注意：/dev/input/jsX默认属于root:input，普通用户不在input组里的话读不了。解决办法是把当前用户加入input组：
sudo usermod -aG input $USER然后重新登录（或者newgrp input）让组权限生效。这一步不做的话，jstest-gtk 打开后设备列表会是空的，或者提示权限不足。
3.2 创建虚拟手柄的快速方法
如果你手头没有物理手柄，或者就是要测试虚拟手柄，可以用uinput快速创建一个。最省事的方式是用 Python 的evdev库写个小脚本：
from evdev import UInput, AbsInfo, ecodes cap = { ecodes.EV_KEY: [ecodes.BTN_A, ecodes.BTN_B, ecodes.BTN_X, ecodes.BTN_Y], ecodes.EV_ABS: [ (ecodes.ABS_X, AbsInfo(0, -32768, 32767, 0, 0, 0)), (ecodes.ABS_Y, AbsInfo(0, -32768, 32767, 0, 0, 0)), ], } ui = UInput(cap, name='virtual-gamepad', version=0x1) print('虚拟手柄已创建，按 Ctrl+C 退出') ui.device.close()运行这个脚本需要先装python3-evdev：
sudo apt install python3-evdev脚本跑起来之后，再开一个终端执行ls /dev/input/js*，应该能看到多了一个js1（或者js0，取决于原来有没有设备）。这个就是虚拟手柄的节点。
注意：uinput 模块需要内核支持，大多数发行版默认已加载。如果
/dev/uinput不存在，执行sudo modprobe uinput加载模块。
3.3 用 jstest-gtk 验证轴与按键映射
打开 jstest-gtk，界面左侧会列出所有检测到的 joystick 设备。选中你刚创建的虚拟手柄（通常显示为virtual-gamepad或类似的名称），右侧就会出现轴滑块和按键指示灯。
这时候你可以做几件事来验证配置：
第一，确认轴的数量和范围。jstest-gtk 会显示每个轴的当前值和最小/最大值。上面脚本里 ABS_X 设的是 -32768 到 32767，滑块应该能在整个范围内移动。如果你在脚本里写事件往 ABS_X 写值，滑块会实时跟着动。
第二，确认按键映射。每个 BTN_A、BTN_B 对应一个指示灯，脚本里发按键事件时对应的灯会亮。如果灯亮了但编号不对，说明你的映射逻辑有问题。
第三，检查是否有意外的轴或按键。有时候虚拟手柄创建时能力集（capability）设多了或设少了，jstest-gtk 能直观地暴露出来。
我自己的习惯是：创建虚拟手柄后，先写一个简单的测试循环，依次触发每个轴和每个按键，同时在 jstest-gtk 里观察。这样一轮下来，映射表就验证完了，比看代码靠谱得多。
4. 实操过程中容易踩的坑与排查思路
4.1 设备节点不出现或权限被拒
最常见的问题是创建了虚拟手柄但/dev/input/jsX没出现。原因通常有三个：一是 uinput 模块没加载，lsmod | grep uinput确认一下；二是创建脚本没有足够的权限写/dev/uinput，需要 root 或者把用户加入input组；三是能力集配置有问题，内核拒绝了设备注册。
排查顺序建议从下往上：先看脚本有没有报错，再看dmesg | tail有没有内核层面的错误信息，最后检查权限和模块。
4.2 jstest-gtk 能看到设备但数值不动
这种情况一般是事件没有正确写入。检查你的脚本里是不是只创建了 UInput 对象但没有调用ui.write()发事件。另外注意，有些轴需要先发一个初始值，jstest-gtk 才会开始显示变化。
还有一个容易忽略的点：如果你同时开了多个程序读同一个 js 设备，可能会出现事件被其中一个消费掉的情况。调试时尽量只开 jstest-gtk 一个读取端。
4.3 轴方向或范围与预期不符
Linux 手柄的轴有符号和无符号两种表示方式。ABS_X 这类通常是有符号的，范围 -32768 到 32767；而 ABS_Z、ABS_RX 等有些驱动会用 0 到 255。如果你在脚本里按一种范围写值，但能力集里声明的是另一种，jstest-gtk 显示就会很奇怪。
解决办法是在创建 UInput 时明确指定 AbsInfo 的 min/max，并且写入的值不要超出这个范围。我一般统一用 -32768 到 32767，兼容性最好。
4.4 虚拟手柄在目标应用中不生效
jstest-gtk 能看到不代表所有应用都能用。有些应用（特别是通过 SDL 库读手柄的游戏）会缓存设备列表，虚拟手柄创建后需要重启应用才能识别。另外 SDL 有自己的手柄映射数据库，如果虚拟手柄的厂商 ID 和产品 ID 不在数据库里，可能需要手动配置映射。
排查方法：先用jstest-gtk确认系统层面没问题，再检查目标应用的日志看它有没有枚举到设备。如果是 SDL 应用，可以设SDL_JOYSTICK_DEVICE环境变量指定设备路径试试。
5. 几个提升调试效率的实用技巧
5.1 用 udev 规则固定设备节点
虚拟手柄每次创建时分配的jsX编号可能变，这会让依赖固定路径的脚本很头疼。可以写一条 udev 规则，根据设备名称创建固定符号链接：
# /etc/udev/rules.d/99-virtual-gamepad.rules KERNEL=="js*", ATTRS{name}=="virtual-gamepad", SYMLINK+="input/virtual-gamepad"这样不管实际节点是 js0 还是 js5，都可以通过/dev/input/virtual-gamepad访问。
5.2 结合 evtest 做交叉验证
jstest-gtk 看的是 joystick 接口的解析结果，有时候你想确认原始事件是否正确，可以用evtest对照看。两个工具同时开着，一个看原始事件，一个看解析后的轴值，能快速定位是事件生成的问题还是解析的问题。
5.3 写一个自动化验证脚本
如果经常需要验证虚拟手柄配置，可以把测试逻辑写成脚本：创建虚拟手柄、依次触发所有轴和按键、读取 jstest 接口的输出、比对预期值。这样每次改完配置跑一遍脚本就行，不用手动在 GUI 里点。
#!/bin/bash # 简单示例：读取 js0 的前几个事件 timeout 2 jstest --event /dev/input/js0 | head -20这个命令会打印出 js0 设备的事件流，适合快速确认设备是否在工作。
5.4 注意内核版本差异
不同内核版本对 uinput 的支持细节有差异。比如较老的内核（4.x 以前）对某些 ABS 类型的支持不完整，创建虚拟手柄时可能会失败。如果遇到莫名其妙的问题，先uname -r看一下内核版本，再查一下对应版本的 uinput 文档。我实测下来，5.4 及以上的内核基本没遇到过兼容性问题。
6. 常见问题速查表
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| jstest-gtk 设备列表为空 | 权限不足或没有设备 | 检查用户是否在 input 组，ls /dev/input/js* |
| 虚拟手柄创建后节点不出现 | uinput 未加载或能力集错误 | lsmod | grep uinput，检查脚本报错 |
| 轴滑块不动 | 事件未写入或范围不匹配 | 确认脚本调用了 write，检查 AbsInfo 范围 |
| 按键指示灯不亮 | 按键码未在能力集中声明 | 检查 EV_KEY 列表是否包含对应 BTN 码 |
| 目标应用识别不到 | 应用缓存了设备列表 | 重启应用，检查 SDL 映射配置 |
| 设备编号每次都变 | 没有固定节点规则 | 添加 udev 规则创建符号链接 |
这张表是我自己调试时总结的，基本上覆盖了八成以上的问题。遇到新问题的时候，先按表里的顺序排查一遍，大部分情况都能解决。
7. 我个人在实际操作中的几点体会
用 jstest-gtk 调试虚拟手柄这件事，说到底核心就一句话：先确认系统层面设备正常，再排查应用层面映射问题。很多人一上来就在应用里调，结果绕了半天发现是/dev/input/jsX权限不对，白白浪费时间。
我自己的习惯是，任何手柄相关的调试，第一步永远是开 jstest-gtk 看一眼。设备在不在、轴动不动、按键亮不亮，三秒钟就能判断问题出在哪一层。这个工具虽然简单，但在这个环节上比任何其他工具都直接。
另外提醒一点：虚拟手柄的能力集配置最好一次到位，不要创建之后再改。因为很多应用在设备创建时就会读取能力集并缓存，中途修改能力集可能导致应用行为异常。如果确实需要改，先把虚拟手柄销毁，改完再重新创建。
最后分享一个小技巧：如果你在开发一个需要手柄输入的应用，可以在代码里加一个调试开关，打开时自动创建虚拟手柄并启动 jstest-gtk，这样开发和测试的切换成本几乎为零。这个做法我在几个项目里都用过，实测能省不少来回折腾的时间。
