企业官网建设流程全解析

QtScrcpy 投屏实操手册：USB 连屏、按键映射 JSON 写法与多机群控一次讲清

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

QtScrcpy 是一款把 Android 屏幕实时搬到桌面的开源投屏控制工具：它通过 USB 或 Wi-Fi 连接手机，不需要 root，也不会在手机上安装任何常驻应用，Windows、macOS、Linux 三个平台都能跑。下文按"连上设备 → 键鼠接管 → 多机群控 → 排障"这条完整工作流展开，帮你从第一次连屏一直走到批量管理设备。

一、把手机屏幕搬到桌面：USB 连接与性能基线

1.1 连接前只需满足两个条件

• 手机系统为 Android 5.0 及以上（API 21 起步）
• 「开发者选项」中已开启 USB 调试

用数据线把手机接入电脑，打开 QtScrcpy 后点击「一键 USB 连接」，1 秒以内即可看到第一帧画面。它的典型基线是 30~60fps 帧率、1920×1080 以上分辨率、约 35~70ms 端到端延迟，且整个过程不索取 root 权限。

QtScrcpy 在 Windows 上的运行界面：左侧启动配置与设备列表，右侧为手机画面

1.2 启动配置里先调好分辨率与比特率

「启动配置」决定每次投屏的行为，值得先花一分钟认识：

• 比特率 / 分辨率：比特率决定画质上限，分辨率决定清晰度，两者都要和带宽匹配
• 录像格式 / 保存路径：对应"本地录屏"功能，边投屏边存视频
• 仅后台录制：启动服务不弹画面窗口，只录屏，适合批量挂机录制
• 窗口置顶：让画面窗口压在其它应用之上
• 自动息屏：连上后自动熄掉手机屏幕，省电也防旁人偷看
• 使用 Reverse：连接报错more than one device时，去掉勾选再试

经验值：日常看消息、点应用 720p 足够；录教程或需要读清小字再拉高。

二、拔掉数据线：无线连接九步流程

无线投屏让手机在局域网内自由活动，核心是先把手机的 adbd 服务跑起来。完整步骤如下：

1. 手机与电脑接入同一 Wi-Fi，并在「开发者选项」打开「USB 调试」
2. 用数据线临时连上手机，点「刷新设备」获取设备号
3. 点「获取设备 IP」，把地址填进无线连接区域
4. 点「启动 adbd」——这是 Android 的调试守护进程，跑起来后手机才接受无线 ADB 连接
5. 点「无线连接」
6. 再次「刷新设备」，列表里会多出一条以 IP 开头的条目，选中它
7. 点「启动服务」，投屏建立

adbd 只需要启动一次：之后拔掉数据线即可，除非它停止运行或手机重启，否则不必再走 USB。

适合演示、直播、移动办公这类不想被线缆束缚的场景。

三、键鼠操作手机：按键映射 JSON 怎么写

按键映射的作用是把键盘按键和鼠标动作翻译成手机屏幕上的触摸事件，规则存放在 keymap/ 目录下的 JSON 文件里，仓库自带了多款游戏的现成映射。

在投屏窗口里左键单击，控制台会打印当前指针的相对坐标，可直接抄进 JSON 的 pos 字段

3.1 先理解两条基础约定

• 坐标是 0~1 的相对值：屏幕宽高都记作 1，(0.5, 0.5)就是正中心，(0.015, 0.042)靠近左上角。1080p 屏幕上(0.5, 0.5)对应像素 (960, 540)
• 按键名用 Qt 枚举：如Key_A、Key_Space、LeftButton，完整列表可查 Qt 官方 Key 枚举文档

3.2 一份可读懂的最小示例

映射文件由三部分组成：switchKey定义切换键，mouseMoveMap定义鼠标移动映射，keyMapNodes是按键映射数组。下面是一个 10 行内的最小结构：

{ "switchKey": "RightButton", "mouseMoveMap": { "startPos": { "x": 0.7, "y": 0.41 }, "speedRatioX": 3.25, "speedRatioY": 1.25 }, "keyMapNodes": [ { "type": "KMT_CLICK", "key": "Key_Space", "pos": { "x": 0.9, "y": 0.8 } } ] }

含义是：按住鼠标右键切换映射模式；鼠标移动映射成从 (0.7, 0.41) 起始的手指拖动（转视野用）；空格键模拟点按屏幕右下角 (0.9, 0.8)。保存为mygame.json放进 keymap/ 即可被识别。

3.3 五种映射类型怎么选

mouseMoveMap的speedRatioX / speedRatioY控制灵敏度，数值越大灵敏度越低（Y 轴内部按 2.25 比例平移）；smallEyes可指定一个按键，按下后鼠标移动改从smallEyes.pos出发，方便开镜。

3.4 从写文件到生效的五步

1. 把 JSON 文件放进 keymap/ 目录
2. 点「刷新脚本」，让 QtScrcpy 扫描目录
3. 在列表里选中你的脚本
4. 连上手机并启动服务后，点「应用脚本」
5. 按~键进入自定义映射模式；再按一次~切回普通控制

坐标怎么取？两种方式任选：

• 在投屏窗口里左键单击，控制台会打印当前指针的相对坐标（即上图中 pos 值），直接抄进 JSON
• 手机「开发者选项」打开「指针位置」，触摸屏幕直接读像素坐标，再换算成 0~1 相对值

玩和平精英等 FPS 时，记得把载具设置改成单摇杆模式，方向盘映射才能正常驱动。

键鼠映射生效后的游戏画面：方向键控制走位，鼠标控制视角

四、一台电脑管多台手机：群控、批量操作与剪贴板

4.1 同时连多台设备

QtScrcpy 允许同时连接多台设备，每台手机一个画面窗口，可以逐台精细操作，也可以批量执行同一动作。仓库中的 groupcontroller 模块就是为分组控制设计的。作者基于同一技术路线的产品「极限投屏」在 OTG 模式、低分辨率低帧率下，单台电脑可管理 500 台以上手机——QtScrcpy 本身也支持多设备连接与批量操作，具体规模受你的网络与 CPU 限制。

多设备快速投屏的管理视图，适合批量初始化与兼容性测试

4.2 三个高频批量操作

• 拖 APK 安装：把 .apk 文件拖进画面窗口，即推送到手机并安装
• 拖文件传输：把任意文件拖进画面窗口，即推送到设备
• 剪贴板双向同步：Ctrl+C把设备内容拷到电脑；Ctrl+Shift+V把电脑内容注入设备；Ctrl+V按文本事件发送（不支持非 ASCII 字符）

群控的典型场景：兼容性测试、批量初始化配置、账号矩阵操作。

五、快捷键速查表与使用建议

下表整理自项目文档的高频快捷键，建议先记前 5 个：

使用建议：

• Ctrl+G切 1:1 像素显示，排查 UI 细节最清楚
• 鼠标中键模拟主页键、右键双击模拟返回键，高频操作可以完全脱离键盘
• 投屏窗口与手机屏幕比例不一致时会自动补黑边，Ctrl+W或双击黑边即可去除

六、连接与控制排障：8 个常见报错的处理办法

按出现频率从高到低整理，报错原文都列出来方便你对照控制台：

1. adb server version (41) doesn't match this client (39)：电脑里同时跑了不同版本的 adb。在任务管理器结束全部 adb 进程，或在 config/config.ini 中把AdbPath指向当前在用的 adb 可执行文件
2. 插线后刷新设备列表为空：通常是电脑没识别手机。先装任一手机助手连成功一次（装好驱动），再回来点「刷新设备」
3. 能看到画面但点不动：小米等机型需要额外授权。进「开发者选项 → USB 调试（安全设置）」，打开「允许模拟点击」
4. Windows 上画面模糊：右键QtScrcpy.exe → 属性 → 兼容性 → 更改高 DPI 设置 → 覆盖高 DPI 缩放行为 → 缩放执行方选"应用程序"。另注意窗口远小于屏幕时文字必然发虚，先拉大窗口
5. Could not open video stream：原因多样，最省事的解法是在启动配置里选一个更低的分辨率
6. 玩和平精英上下车后映射失效：游戏切场景导致触摸点错位，连按两次~键重新切换映射模式即可恢复
7. 无法输入中文：手机端安装搜狗或 QQ 输入法，即可把电脑上的中文粘贴进手机
8. 能控制但看不到画面，控制台出现shader program is not linked一类报错：显卡不支持当前渲染方式，在 config/config.ini 把UseDesktopOpenGL改为1（DX 硬解）或2（OpenGL 硬解）再试

七、读源码与二次开发：技术栈、编译与贡献

对投屏链路好奇，可以直接读 docs/DEVELOP.md：手机端scrcpy-server负责采集屏幕并做 H.264 编码，经 socket 把裸视频流传给电脑端；QtScrcpy 用 FFmpeg 解码、用 OpenGL 渲染，解码线程与渲染线程用双缓冲交换，把端到端延迟压到 35~70ms。整体技术栈是C++ + Qt（信号槽异步模型）+ OpenGL + FFmpeg + CMake，相比原版 scrcpy 的主要差异：UI 从 SDL 换成 Qt、渲染从 SDL 换成 OpenGL、语言从 C 换成 C++、同步改异步，并额外支持自定义按键映射与多点触控。

源码目录组织清晰：界面层在 QtScrcpy/ui/，OpenGL 视频渲染在 QtScrcpy/render/，音频输出在 QtScrcpy/audio/，跨平台鼠标透传在 QtScrcpy/util/mousetap/。

编译只需：

1. 准备Qt 5.12+（Windows 用 MSVC 2019）
2. 克隆时带上子模块：git clone --recurse-submodules，仓库地址https://gitcode.com/GitHub_Trending/qt/QtScrcpy
3. Windows 用 QtCreator 打开根目录CMakeLists.txt，编 Release；Linux 直接跑 ci/linux/build_for_linux.sh"Release"
4. 产物在output/x64/Release

想贡献代码：PR 推向dev分支、提交前先变基、按"一个功能点一个 PR"拆分、风格与现有代码保持一致。

八、现在就开始体验

从下载现成版本、USB 连线、打开 USB 调试这三步开始，你就能走完"连屏 → 键鼠接管 → 群控"的完整工作流；遇到报错回到第六节对号入座；想二次开发则克隆源码，从CMakeLists.txt入手先把编译跑通。

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