如何把手游键位完整搬上键鼠？QtScrcpy 键鼠映射配置实战笔记

如何把手游键位完整搬上键鼠？QtScrcpy 键鼠映射配置实战笔记

【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy

QtScrcpy 是一款安卓实时投屏与控制工具，通过 USB 或局域网连接手机后，可以把键盘、鼠标的输入转换成屏幕上的触摸事件，核心扩展能力就是键鼠映射：一份 JSON 文件，定义哪个键位对应屏幕上的哪个动作。下面按"让一个映射文件真正跑起来"的思路，讲清楚从连接设备、应用脚本，到坐标校准、灵敏度调优和常见故障排查的完整流程。

一、映射文件的三部分结构

映射文件是 JSON 格式，放在 keymap/ 目录下才会被识别，完整编写规则见 docs/KeyMapDes_zh.md。一份完整的文件由三部分组成：

• switchKey：普通镜像控制与映射模式之间的切换键，预设文件大多取Key_QuoteLeft（即~键）。
• mouseMoveMap（可选）：把鼠标移动转成连续的手指拖动，用于 FPS 类游戏的视角控制，包含拖动起点startPos、灵敏度比例speedRatioX/speedRatioY，以及辅助微调的"小眼睛"smallEyes。
• keyMapNodes：通用按键数组，把每个键盘键对应到一次触摸动作。

坐标体系要先说清楚：所有坐标都是相对值，以屏幕左上角为原点，宽高各归一化为 1，(0.5, 0.5) 就是屏幕中心。这意味着同一份文件在不同分辨率的设备上通用，也是后面调参的基础。

keyMapNodes中可用的节点类型共五种：

一个最小可用的片段长这样：

"switchKey": "Key_QuoteLeft", "keyMapNodes": [ {"type":"KMT_CLICK","key":"Key_Space", "pos":{"x":0.5,"y":0.5}} ]

按键名使用 Qt 的键枚举，如Key_W、Key_Shift、LeftButton，可以在 Qt 文档的 Key enum 中查询。

二、让映射生效：连接、应用、切换三步

1. 手机端开启开发者选项中的 USB 调试；小米等机型还需要在 USB 调试子菜单里打开"模拟点击"，否则会出现有画面但无法控制的状况（见 docs/FAQ.md）。
2. 连接设备：USB 连接后点击"刷新设备列表"；走局域网则需先通过 USB 启动 adbd，再选择以 IP 开头的那台设备。
3. 点击"启动服务"，正常情况下约 1 秒内视频窗口出画面。
4. 点击"刷新脚本"确认目标文件出现在列表中，选中后点击"应用脚本"。
5. 按下~（即文件里定义的 switchKey）进入映射模式，再按一次回到普通触控。

注意：切换键不是固定为~。预设文件中也有把 switchKey 设为鼠标右键的写法（如第五人格），以文件内定义为准。

三、坐标与灵敏度：两个最常调错的地方

取坐标的三种途径：

• 手机开发者选项中打开"显示指针位置"，触摸屏幕时直接读出坐标，再除以屏幕宽高得到相对值；
• 开启鼠标移动映射后，鼠标左键单击会把当前 pos 打印到 QtScrcpy 控制台，可直接照抄；
• 以预设文件为参照，只替换自己游戏里的按钮位置。

灵敏度方向，是最容易记反的一处：speedRatioX/speedRatioY的数值越大，鼠标需要移动的距离越长，手感越"沉"；两者均要求不小于 0.001（整体 speedRatio 需大于 0.00225）。瞄准发飘就调大数值，感觉拖不动就调小。自带的和平精英配置取 X=3.25、Y=1.25，可作为起点参照。

smallEyes则用于微调：按下指定键后，拖拽起点切换到smallEyes.pos处且活动范围缩小，相当于给准星加了一档低速档。

建议一次只改一个参数并在游戏内验证。自己的映射文件按上述格式编写后放入 keymap 目录，用自带预设当模板，比从零写要快得多。

四、按品类看键位：以《第五人格》为例

预设目录里除了射击类，还有 keymap/identityv.json 这份"移动 + 视角 + 技能"混合布局的完整样例，摘录如下：

这份文件里有两个值得留意的做法：

• 走位用KMT_STEER_WHEEL，centerPos加四个方向的 offset，WASD 四键即覆盖八向移动，比逐方向单独点击更接近摇杆手感；
• 菜单类按键（如 Esc 退出）设置了switchMap: true，按下时释放鼠标锁定，方便在菜单里用指针导航，用完切回映射即可。

其他品类同理：FPS 参考 gameforpeace.json，Apex 手游参考 FRAG.json，短视频类参考 tiktok.json（方向键模拟上滑下滑翻页）。品类不同，布局逻辑不同，但文件结构完全一致。

五、多开与批量控制时的注意点

QtScrcpy 支持同时打开多个设备的视频窗口，键鼠操作可同步下发到所有已连接设备。多开场景下建议：

• 先固定窗口布局与窗口置顶，再逐台应用脚本，避免操作串窗口；
• 批量使用前适当降低分辨率与比特率，投屏负载是单台电脑可带设备数的主要瓶颈；
• 每台设备的映射文件可以不同，按设备单独选择脚本即可。

六、排查清单：映射"看起来没生效"

按顺序检查这四点，能覆盖绝大多数情况：

1. 当前不在映射模式：再按一次 switchKey 切换；和平精英等在上下车后会出现触摸点偏移，连续按两次切换键可恢复；
2. 设备已断开，或无线连接掉线后 adbd 未重新启用；
3. 机型缺少"模拟点击"授权：有画面、无响应，典型于小米等品牌；
4. adb 版本冲突：控制台出现 version 不匹配报错时，结束 adb 进程，或在 config/config.ini 中把 AdbPath 指向当前使用的 adb。

更多问题记录在 docs/FAQ.md，其中"画面不清晰""Could not open video stream"等条目分别对应 DPI 缩放与分辨率设置，可按图索骥。

【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy