QtScrcpy 键鼠映射完整指南：3 分钟把手游变成键鼠操作

【免费下载链接】QtScrcpyAndroid实时投屏软件，此应用程序提供USB(或通过TCP/IP)连接的Android设备的显示和控制。它不需要任何root访问权限项目地址: https://gitcode.com/barry-ran/QtScrcpy

晚上窝在沙发，手指挤在手机小屏里搓方向、点技能，一局打下来手是酸的。而用 QtScrcpy 把手机画面投到电脑后，同一局游戏换成了 WASD 加鼠标：左键开枪、空格起跳、移动鼠标转视角。QtScrcpy 是一款免费开源的 Android 投屏软件，除投屏和基础控制外，它的键鼠映射功能可以把 JSON 脚本里定义的键盘、鼠标动作转换成手机上的触摸事件。读完这篇教程，你能独立完成一次投屏连接，并写出一份能上手的按键映射脚本。

能力速览

最短上手路径 ⏱️

从完全没配置过，到亲眼看到手机画面出现在电脑窗口，预计 5 分钟。

1. 开启 USB 调试：手机进入"设置 → 关于手机"，连续点击版本号 7 次解锁开发者选项，再回到开发者选项打开 USB 调试开关；部分机型还要在"USB 调试（安全设置）"里允许模拟点击，缺少这步会导致后面能看画面却点不动屏幕。
2. 把软件放到电脑：从仓库 Release 页下载对应平台的免编译压缩包（已内置 adb），或用git clone https://link.gitcode.com/i/f4620807b84a19057377e20b15293a04自行编译，Windows / macOS / Linux 都支持。
3. 插上设备验证：数据线连接后，点"刷新设备"，设备号出现在列表里即说明 adb 识别成功；点"启动服务"，约 1 秒后画面出现。
4. 改用 WiFi 连接（可选）：手机与电脑同网段时，依次点"获取设备 IP → 启动 adbd → 无线连接 → 刷新设备"，选中 IP 地址对应的设备再启动服务，之后数据线可以拔掉。

核心功能详解：键鼠映射怎么工作

原理一句话

映射脚本是一个 JSON 文件：switchKey定义切换键，mouseMoveMap定义鼠标移动对应的视角拖动，keyMapNodes把每个按键绑定到屏幕上的一个触摸点。所有坐标都是 0~1 的相对值（左上角为原点），同一份脚本可以通用不同分辨率的手机。

脚本统一放在 keymap 目录，点界面上的"刷新脚本"就是重新扫描这个目录。

最小可运行示例

下面这份脚本只保留跑通映射所需的最少字段，存为keymap/myfirst.json即可：

{ "switchKey": "Key_QuoteLeft", "mouseMoveMap": { "startPos": { "x": 0.5, "y": 0.25 }, "speedRatioX": 3.25, "speedRatioY": 1.25 }, "keyMapNodes": [ { "comment": "单点测试", "type": "KMT_CLICK", "key": "Key_Space", "pos": { "x": 0.5, "y": 0.5 } } ] }

加载方式：选中该脚本 → 连接手机 → 启动服务 → 点"应用" → 按一次~（即脚本里的 switchKey）进入映射模式。预期效果：脚本加载成功，空格会在屏幕中心点出一个触摸，鼠标移动开始转视角，再按一次~回到普通触控。

获取脚本里的精确坐标

最省事的办法：应用映射后，在投屏窗口里用鼠标左键点一下，控制台会直接打印该点的相对坐标 pos，填进脚本即可。

接入真实场景：FPS 游戏的完整映射

仓库自带的 keymap/gameforpeace.json（和平精英）是一个完整范本：移动、探头、开火、开镜、蹲、趴、换弹共二十多个节点，鼠标左键开火、右键开镜。核心片段长这样：

{ "comment": "方向盘", "type": "KMT_STEER_WHEEL", "centerPos": { "x": 0.16, "y": 0.75 }, "leftOffset": 0.1, "rightOffset": 0.1, "upOffset": 0.27, "downOffset": 0.2, "leftKey": "Key_A", "rightKey": "Key_D", "upKey": "Key_W", "downKey": "Key_S" }

预期效果：centerPos对准游戏里虚拟摇杆中心，WASD 分别把摇杆按对应 offset 幅度拖出，人物即向该方向移动；配合mouseMoveMap转视角，操作节奏就接近端游了。

几个值得注意的行为：

• 启用mouseMoveMap后鼠标指针会被隐藏，移动范围受限，所有移动都换算成从startPos出发的虚拟手指拖动。
• 开车场景下游戏会创建新界面，导致触摸点失效；README 建议把载具设置改为"单摇杆模式"，失效时连续按两次切换键可以恢复。
• 不会手写规则的话，可用作者配套的 QuickAssistant 工具做界面化编辑（入口见 docs/KeyMapDes_zh.md）。

典型场景实战

FPS / 射击类（以 gameforpeace.json 为基准）

MOBA / 休闲类（适合从 keymap/test.json 起步改）

调优指南 🔧

两条经验：

• FPS 游戏建议水平灵敏度略高于垂直（水平数值给得小一些）；MOBA 和休闲游戏两轴保持同值更不容易打转。
• 手感不对时先动 speedRatioX/Y，一次改 0.25 左右试一局；startPos 放偏了怎么调灵敏度都不舒服，先对齐位置。

常见问题快查

现象：应用脚本后按键毫无反应。排查：看是不是还在普通模式。解决：按一次 switchKey（默认~）切进映射模式；确认点过"应用"而不是只刷新了脚本列表。

现象：USB 插好，刷新设备列表却是空的。排查：先确认手机侧的调试授权弹窗是否点了允许。解决：列表仍为空时装一个手机助手类应用验证连接；报adb server version ... doesn't match则结束任务管理器里的 adb 进程，或在 config.ini 的AdbPath指向当前用的 adb。

现象：画面正常，但点屏幕没反应。排查：小米等机型默认拦截外部模拟点击。解决：开发者选项里打开"USB 调试（安全设置）"中的允许模拟点击项，再重新连接。

现象：能控制但画面发虚、文字发毛。排查：窗口远小于设备原生分辨率，或 Windows 高 DPI 缩放在作怪。解决：窗口拉大，或在QtScrcpy.exe属性 → 兼容性 → 更改高 DPI 设置中把缩放行为设为"应用程序"。

检查清单

配置前

• 开发者选项已开启 USB 调试，必要时含模拟点击权限
• 映射 JSON 已放入keymap目录且格式校验通过
• 刷新设备后列表能看到设备号

配置中

• switchKey 没有和映射里的 key 撞键
• 每个触摸坐标都用调试坐标或指针位置核对过
• 节点类型选对：单点用 KMT_CLICK、双击用 KMT_CLICK_TWICE、滑动用 KMT_DRAG

验收时

• 试打一小局，按调优建议微调 speedRatioX/Y
• 按切换键能立刻释放鼠标、切回普通模式
• "应用"后窗口无报错，各节点触摸点位置准确

写在最后

投屏加键鼠映射，本质上就是让你把手机当成一台"带触屏的游戏手柄"来用：先保证连接稳，再把坐标和灵敏度打磨到自己顺手。下一步建议翻一翻 docs/KeyMapDes_zh.md 里全部节点类型的字段说明，照抄 keymap/ 目录下的 tiktok、identityv 等现成脚本改参数，有兴趣了解实现细节再进入 QtScrcpy/QtScrcpyCore/ 源码目录看看映射是怎么被执行的。

【免费下载链接】QtScrcpyAndroid实时投屏软件，此应用程序提供USB(或通过TCP/IP)连接的Android设备的显示和控制。它不需要任何root访问权限项目地址: https://gitcode.com/barry-ran/QtScrcpy