企业官网建设流程全解析

QtScrcpy 安卓投屏实战：从 USB 连接到 JSON 键鼠映射

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

QtScrcpy 是一款基于 Qt 的安卓投屏与控制软件，通过 USB 或 WiFi 连接手机后实时显示画面并支持反向操控，无需 Root，也不在手机上安装任何软件。官方给出的性能指标为 30～60 fps、分辨率 1920×1080 以上、投屏延迟 35～70 ms，首帧在 1 秒内可见。Windows、macOS、Linux 三大平台均提供预编译版本，项目基于 Apache 2.0 协议开源。下面按"先连上、再操控、最后调优"的顺序，把使用路径讲清楚。

首次连接：环境准备与 USB / 无线两种方式

三个前置条件

• 安卓设备版本不低于 Android 5.0（API 21）；
• 手机上进入"设置 > 关于手机"，连续点击"版本号" 7 次开启开发者模式，再在"开发者选项"中启用 USB 调试；
• 电脑已装好 QtScrcpy 或 ADB 驱动；如果只打算自己编译源码，则额外需要 CMake 和 Qt 开发环境：

git clone https://gitcode.com/GitHub_Trending/qt/QtScrcpy

USB 与无线连接

推荐用 USB 数据线连接后点击界面右上角的"刷新设备"；设备被识别后选择对应设备并点击"连接"，画面即可出现。无线连接（WiFi 投屏）需要先通过 USB 建立一次连接，获取手机局域网 IP 后，在软件中切换到网络地址连接，之后即可拔掉数据线。

投屏后常用的 7 个快捷键

JSON 键位文件的结构与坐标规则

键鼠映射是 QtScrcpy 区别于普通投屏工具的核心能力：把键盘按键模拟成屏幕触摸点，把鼠标移动模拟成手指拖拽。所有映射文件都是 JSON 格式，统一放在 keymap/ 目录，程序启动扫描该目录自动识别。仓库自带 5 份脚本：和平精英（gameforpeace.json）、抖音（tiktok.json）、第五人格（identityv.json）和两份测试配置。

坐标统一使用相对坐标：屏幕宽和高各表示为 1，(0.5, 0.5) 即屏幕中心。以 1920×1080 为例，(0.16, 0.75) 对应像素位置约 (307, 810)。文件里的两个关键字段：

• switchKey：映射模式的切换键，默认是Key_QuoteLeft（~键，数字 1 左边）。普通模式下按键是鼠标点击，按下切换键后进入自定义映射模式，再按一次切回；
• keyMapNodes：按键映射数组，每个节点声明一个type、按键码key和触摸位置pos。

type支持 5 种：KMT_CLICK（普通点击）、KMT_CLICK_TWICE（双击）、KMT_CLICK_MULTI（多点连续点击）、KMT_DRAG（拖拽）、KMT_STEER_WHEEL（方向盘，用 4 个按键模拟 FPS 游戏的左摇杆移动）。顶层还有mouseMoveMap字段，把鼠标移动映射为以startPos为起点的手指拖动，用于控制人物视角，speedRatioX/speedRatioY两个参数调节灵敏度，数值越大越不敏感。

以和平精英为例，一段典型配置：

{ "switchKey": "Key_QuoteLeft", "mouseMoveMap": { "startPos": { "x": 0.57, "y": 0.26 }, "speedRatioX": 3.25, "speedRatioY": 1.25 }, "keyMapNodes": [ { "comment": "跳", "type": "KMT_CLICK", "key": "Key_Space", "pos": { "x": 0.96, "y": 0.70 } }, { "comment": "方向盘", "type": "KMT_STEER_WHEEL", "centerPos": { "x": 0.16, "y": 0.75 }, "upKey": "Key_W", "downKey": "Key_S", "leftKey": "Key_A", "rightKey": "Key_D" } ] }

配置新键位的四步流程

1. 在 keymap 目录新建一个 JSON 文件，按键码命名参考 Qt 的Qt::Key枚举（如Key_W、Key_Space）；
2. 点击软件上的"刷新脚本"让程序重新扫描目录；
3. 在脚本下拉列表中选择该文件，连接设备后点击"应用脚本"；
4. 游戏中按下~键切到自定义映射模式即生效。玩和平精英等游戏时，建议把载具设置改为单摇杆模式，否则方向盘映射会被游戏自带逻辑干扰。

多设备组控、录制截图与性能调优

批量控制多台手机

组控功能把同一批已连接设备合并为一个控制组，键盘、鼠标操作会同步下发到组内所有手机。典型场景是游戏多开同步、应用批量测试和演示同步播放。

屏幕录制与截图

界面内置录屏功能，支持指定保存路径和格式，也支持后台录制（画面最小化后继续录）。截图按单台或整组设备触发，保存为本地图片。录制分辨率和帧率跟随当前投屏设置，调优时与投屏参数一起考虑即可。

性能调优的三个手段

• 优先 USB 连接；WiFi 环境下尽量降低分辨率和帧率，用流畅度换延迟；
• Windows 高分屏出现画面模糊时，右键 QtScrcpy.exe > 属性 > 兼容性 > 更改高 DPI 缩放，勾选"由应用程序执行缩放"；
• 报错Could not open video stream时，把分辨率调低一档再试。

连接失败、映射失效与画面卡顿的排查顺序

• 刷新后设备列表为空：多为 ADB 版本冲突（控制台提示adb server version doesn't match this client）。在任务管理器中结束 adb 进程后重试，或修改config.ini里的AdbPath指向当前使用的 adb。
• 有画面但无法控制：小米等机型需要在 USB 调试中额外开启"允许模拟点击"权限。
• 映射按了没反应：确认已按下切换键~进入映射模式；应用脚本后如果切换游戏内场景（如上下车）导致触摸点失效，连按两次~可恢复。
• 能控制但看不到画面：控制台若报shader program is not linked，说明显卡不支持当前渲染方式，在config.ini中把解码方式改为 1 或 2 再试。
• 画面卡顿：依次尝试降低分辨率与帧率、改用 USB 连接、关闭其他占用 GPU 的程序。

获取精确触摸坐标的两种方式

自定义映射时坐标是最大的工作量。方法一：开启自定义映射模式后，在画面上用鼠标左键单击，控制台会直接输出该点的pos相对坐标，复制进 JSON 即可。

方法二：在开发者选项中打开"显示触摸坐标"和"指针位置"，用手指点击屏幕，状态栏上方会显示像素坐标，再自行除以屏幕宽高换算成 0～1 的相对值。

仓库内的文档与配置资源索引

• docs/：KeyMapDes_zh.md 是键位映射格式的完整说明，FAQ.md 收录了 adb 冲突、中文输入、画面不清晰等高频问题；
• keymap/：5 份可直接参考的键位脚本，和平精英那份覆盖方向盘、探头、开火、小眼睛（Alt 键）等常见需求；
• config.ini：ADB 路径、解码方式等运行时配置；
• screenshot/：各平台界面截图，可对照确认下载版本。

以上覆盖了从首次连接、键位编写到批量控制的完整路径。下一步建议：打开仓库自带的 gameforpeace.json，对照自己屏幕上的按钮位置改一组坐标，跑通第一个自己的键位文件。

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