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

QtScrcpy 安卓投屏实战从 USB 连接到 JSON 键鼠映射【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpyQtScrcpy 是一款基于 Qt 的安卓投屏与控制软件通过 USB 或 WiFi 连接手机后实时显示画面并支持反向操控无需 Root也不在手机上安装任何软件。官方给出的性能指标为 3060 fps、分辨率 1920×1080 以上、投屏延迟 3570 ms首帧在 1 秒内可见。Windows、macOS、Linux 三大平台均提供预编译版本项目基于 Apache 2.0 协议开源。下面按先连上、再操控、最后调优的顺序把使用路径讲清楚。首次连接环境准备与 USB / 无线两种方式三个前置条件安卓设备版本不低于 Android 5.0API 21手机上进入设置 关于手机连续点击版本号 7 次开启开发者模式再在开发者选项中启用 USB 调试电脑已装好 QtScrcpy 或 ADB 驱动如果只打算自己编译源码则额外需要 CMake 和 Qt 开发环境git clone https://gitcode.com/GitHub_Trending/qt/QtScrcpyUSB 与无线连接推荐用 USB 数据线连接后点击界面右上角的刷新设备设备被识别后选择对应设备并点击连接画面即可出现。无线连接WiFi 投屏需要先通过 USB 建立一次连接获取手机局域网 IP 后在软件中切换到网络地址连接之后即可拔掉数据线。投屏后常用的 7 个快捷键快捷键功能Ctrl F全屏切换Ctrl H回桌面Ctrl B返回键Ctrl S应用切换Ctrl M最近任务菜单Ctrl ↑ / Ctrl ↓音量加 / 音量减Ctrl P电源键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 } ] }配置新键位的四步流程在 keymap 目录新建一个 JSON 文件按键码命名参考 Qt 的Qt::Key枚举如Key_W、Key_Space点击软件上的刷新脚本让程序重新扫描目录在脚本下拉列表中选择该文件连接设备后点击应用脚本游戏中按下~键切到自定义映射模式即生效。玩和平精英等游戏时建议把载具设置改为单摇杆模式否则方向盘映射会被游戏自带逻辑干扰。多设备组控、录制截图与性能调优批量控制多台手机组控功能把同一批已连接设备合并为一个控制组键盘、鼠标操作会同步下发到组内所有手机。典型场景是游戏多开同步、应用批量测试和演示同步播放。屏幕录制与截图界面内置录屏功能支持指定保存路径和格式也支持后台录制画面最小化后继续录。截图按单台或整组设备触发保存为本地图片。录制分辨率和帧率跟随当前投屏设置调优时与投屏参数一起考虑即可。性能调优的三个手段优先 USB 连接WiFi 环境下尽量降低分辨率和帧率用流畅度换延迟Windows 高分屏出现画面模糊时右键 QtScrcpy.exe 属性 兼容性 更改高 DPI 缩放勾选由应用程序执行缩放报错Could not open video stream时把分辨率调低一档再试。连接失败、映射失效与画面卡顿的排查顺序刷新后设备列表为空多为 ADB 版本冲突控制台提示adb server version doesnt match this client。在任务管理器中结束 adb 进程后重试或修改config.ini里的AdbPath指向当前使用的 adb。有画面但无法控制小米等机型需要在 USB 调试中额外开启允许模拟点击权限。映射按了没反应确认已按下切换键~进入映射模式应用脚本后如果切换游戏内场景如上下车导致触摸点失效连按两次~可恢复。能控制但看不到画面控制台若报shader program is not linked说明显卡不支持当前渲染方式在config.ini中把解码方式改为 1 或 2 再试。画面卡顿依次尝试降低分辨率与帧率、改用 USB 连接、关闭其他占用 GPU 的程序。获取精确触摸坐标的两种方式自定义映射时坐标是最大的工作量。方法一开启自定义映射模式后在画面上用鼠标左键单击控制台会直接输出该点的pos相对坐标复制进 JSON 即可。方法二在开发者选项中打开显示触摸坐标和指针位置用手指点击屏幕状态栏上方会显示像素坐标再自行除以屏幕宽高换算成 01 的相对值。仓库内的文档与配置资源索引docs/KeyMapDes_zh.md 是键位映射格式的完整说明FAQ.md 收录了 adb 冲突、中文输入、画面不清晰等高频问题keymap/5 份可直接参考的键位脚本和平精英那份覆盖方向盘、探头、开火、小眼睛Alt 键等常见需求config.iniADB 路径、解码方式等运行时配置screenshot/各平台界面截图可对照确认下载版本。以上覆盖了从首次连接、键位编写到批量控制的完整路径。下一步建议打开仓库自带的 gameforpeace.json对照自己屏幕上的按钮位置改一组坐标跑通第一个自己的键位文件。【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考