QtScrcpy 按键映射教程：JSON 结构与键位配置

文件放在哪

映射文件是 JSON 格式，必须放在 QtScrcpy 安装目录下的 keymap 文件夹里，软件启动时会扫描该目录。文件名会作为映射名称出现在界面的下拉框中，新增或修改后重新选择一次即可生效。

仓库自带了几个示例：test.json 演示多点与拖拽，gameforpeace.json 是完整的射击游戏配置，tiktok.json 演示短视频场景。最省事的起点是复制一份改名，再逐步替换坐标与按键。

改之前先备份原文件。映射脚本是纯文本，改坏了不会影响软件本身，但会让人不知道哪一步出了问题。

坐标怎么算

所有坐标都是相对值：屏幕宽度和高度都按 1 计算，原点在左上角。以 1920×1080 的屏幕为例，x=0.5、y=0.5 对应像素坐标 (960,540)。

取坐标有两种快办法：在开发者选项里打开“显示指针位置”，屏幕上会叠加显示当前触摸点；或者直接在投屏窗口里用鼠标左键单击目标位置，控制台会打印该点的 pos，复制进 JSON 即可。

注意相对坐标依赖屏幕比例。同一份脚本换到 20:9 的机型上，纵向位置会明显偏移，所以脚本最好按机型与分辨率分别维护，而不是一份走天下。

一份最小可用的脚本

下面这份配置只做两件事：把 J 键映射为屏幕右下角的单击（开火），把 Q 键映射为左侧区域的连续两次点击（探头）。

{
  "switchKey": "Key_QuoteLeft",
  "keyMapNodes": [
    {
      "comment": "开火",
      "type": "KMT_CLICK",
      "key": "Key_J",
      "pos": { "x": 0.86, "y": 0.78 }
    },
    {
      "comment": "探头",
      "type": "KMT_CLICK_TWICE",
      "key": "Key_Q",
      "pos": { "x": 0.12, "y": 0.35 }
    }
  ]
}

switchKey 是普通模式与映射模式的切换键，默认是反引号键（Key_QuoteLeft）。进入游戏后要先按它开启映射，否则按键仍然按普通键盘输入处理，不会触发触摸。

key 使用 Qt 的键名枚举，常见的有 Key_W、Key_A、Key_Space、Key_Shift、Key_1。完整列表见 Qt 文档中 Qt::Key 的枚举定义。

五种节点类型

按操作形态选择节点类型
type	模拟的动作	必填参数	典型用途
`KMT_CLICK`	按下与抬起各一次触摸	`key`、`pos`	开火、跳跃、技能
`KMT_CLICK_TWICE`	一次按键触发两次点击	`key`、`pos`	探头、切换武器
`KMT_CLICK_MULTI`	按 `clickNodes` 的延迟与坐标连续点击	`key`、`clickNodes`	连招、固定序列
`KMT_DRAG`	从起点拖到终点	`key`、`startPos`、`endPos`	滑屏、开镜、翻页
`KMT_STEER_WHEEL`	四键控制的方向盘	`centerPos`、四个方向键与偏移量	FPS 移动摇杆

KMT_DRAG 还有两个可选参数：dragSpeed 控制拖动速度（0–1，默认 1.0，越大越快），startDelay 指定按下后等待多少毫秒再开始拖动。KMT_CLICK_MULTI 的 clickNodes 是一个数组，每项包含 delay（毫秒）与 pos。

方向盘映射需要四个方向键与四个偏移量配合，下面是从官方示例中摘出的结构：

{
  "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 的位移比例，不是绝对坐标。上调 upOffset 会让“向前”拖得更远，人物移动速度的体感随之变化。

鼠标视角映射

射击类游戏需要把鼠标移动换算成手指拖动，用来转动视角。这段配置写在根节点的 mouseMoveMap 里：

{
  "switchKey": "Key_QuoteLeft",
  "mouseMoveMap": {
    "startPos": { "x": 0.57, "y": 0.26 },
    "speedRatioX": 3.25,
    "speedRatioY": 1.25,
    "speedRatio": 10
  },
  "keyMapNodes": []
}

startPos 是拖动的起始点，通常取屏幕右侧的空白区域。speedRatio 越大，灵敏度越低（官方文档要求大于 0.00225）；speedRatioX 与 speedRatioY 分别控制横向与纵向灵敏度，最小值为 0.001。开启鼠标映射后，鼠标指针会被隐藏并限制在窗口内，按切换键退出映射模式即可恢复。

还有一个可选节点 smallEyes：按住指定键时，鼠标移动改为从 smallEyes.pos 起拖，松开后恢复原起点，用来模拟“小眼睛”观察四周。

调试与微调

先确认处于映射模式：按一次 switchKey，界面状态会变化；没切换时按键不会触发触摸。
坐标偏移时，用“显示指针位置”叠加层核对，不要凭肉眼估。
一次只改一组坐标，改完立刻在目标界面验证，避免多处变动后无法定位问题。
游戏更新 UI 后按钮位置会变，旧脚本需要重新量坐标，这不是脚本失效。
JSON 对逗号与引号很敏感，多一个尾逗号就会整份失效；保存前用编辑器的 JSON 校验功能检查。

常见问题

为什么按键完全没有反应？

先检查是否按了 switchKey 进入映射模式，再确认文件确实放在 keymap 目录、JSON 能被解析、key 使用的是 Qt 键名（如 Key_W 而不是 W）。三者任一不满足都不会触发。

映射文件可以跨机型共用吗？

不建议。坐标是相对值，屏幕比例不同会导致位置偏移；即使分辨率相同，游戏 UI 布局也可能随版本变化。按机型维护更稳。

按键名去哪里查？

官方文档指向 Qt 的 Qt::Key 枚举，键名写作 Key_A、Key_Space、Key_Shift 这种形式。文档地址见本页末尾的参考资料。

一份脚本能同时控制多台设备吗？

脚本本身可以复用，但坐标是否准确取决于每台设备的屏幕比例与游戏界面。多设备群控时建议先用同一型号、同一分辨率验证。

可视化工具

手写 JSON 适合精细控制，但量坐标比较费时。官方文档提到了两类辅助工具：QuickAssistant（项目作者提供的可视化按键工具）与社区项目 ScrcpyKeyMapper（基于 Web 的图形界面，可可视化创建映射、实时测试并导出 JSON）。

工具生成的文件仍然要放进 keymap 目录才生效。如果工具版本与 QtScrcpy 版本差距较大，导出后先对照本文的字段说明检查一遍。

QtScrcpy 按键映射：从零写一份键位脚本