企业官网建设流程全解析

QtScrcpy 完整指南：5 步连接 Android 投屏与键鼠控制

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

QtScrcpy 是一款基于 Qt、OpenGL 与 FFmpeg 的 Android 实时投屏与控制工具，可通过 USB 或 Wi-Fi 连接设备，实现屏幕镜像显示、键鼠控制与屏幕录制，且无需 root。本指南面向初次接触 QtScrcpy 的工程师与普通用户，按序讲解环境准备、设备连接、config.ini 参数配置、keymap 按键映射、CMake 源码编译与常见异常处理。读完并执行完毕，你应在 Windows、macOS 或 GNU/Linux 任一桌面平台独立完成投屏与控机操作。

任务定位：输入、输出与适用边界

本节说明本文的交付物与适用范围，避免读者投入时间后发现需求不匹配。

约束与红线：开始前必须遵守的 4 条规则

本节列出操作中的硬性限制。违反任何一条都会导致连接失败、画面异常或设备状态被破坏。

1. 严禁在设备上 root 或安装任何应用。QtScrcpy 非侵入，仅将服务端推送到设备/data/local/tmp目录运行。
2. 只允许电脑中存在一个 adb 版本。多版本并存时连接会被拒绝，须先统一。
3. 严禁在程序"命令行"输入框执行阻塞命令（如shell），当前版本不支持。
4. 尽量不在多设备场景下将分辨率同时设为最大值；批量投屏时应先调低分辨率与流畅度，保证整体流畅。

前置条件：开始投屏前必须完成的 3 项检查

本节解决"环境没准备好"的问题。以下三项逐项确认，任一缺失都会导致找不到设备或无法控制。

1. 设备版本达标：Android 系统不低于 5.0（API 21）。低于此版本，服务无法启动。
2. ADB 调试已开启：在设备开发者选项中启用 USB 调试；小米等机型须额外开启"允许模拟点击"，否则会出现可见画面但无法控制。
3. adb 版本统一：电脑若运行过其他工具附带的 adb，先结束 adb 进程，或在配置文件中指定统一版本（见异常处理表）。

连接设备：5 步完成 USB / Wi-Fi 投屏

本节解决"怎么连上"的问题。每步按"动作 → 判断 → 结果"执行；判断不通过时，跳至文末异常处理表对应行处置。

第 1 步：接入设备并刷新列表

• 动作：USB 数据线连接设备与电脑，启动程序，点击"刷新设备列表"。
• 判断：设备列表区域刷新并显示一条设备号（序列号）。
• 结果：设备就绪。若列表为空，处理"刷新后无设备"一类故障。

第 2 步：USB 一键连接

• 动作：选中目标设备，点击"一键USB连接"或"启动服务"。
• 判断：控制台输出server start finish in ...，约 1 秒内出现第一帧画面。
• 结果：投屏建立，键鼠操作即刻透传至设备。

第 3 步：（可选）切换无线连接

• 适用条件：希望脱离数据线；电脑与设备须处于同一局域网。
• 动作：点击"获取设备 IP"填入无线区域，点击"启动adbd"，再点击"无线连接"。
• 判断：再次刷新设备列表，出现一个以 IP 地址开头的设备，选中它并启动服务。
• 结果：无线连接建立。adbd 运行期间无需再插数据线，此后重连均走无线。

第 4 步：验证控制链路

• 动作：在投屏窗口内移动鼠标、单击、滚动。
• 判断：设备端出现对应触摸反馈（点击涟漪、滚动位移）。
• 结果：控制通道可用。若无反馈，先检查"允许模拟点击"开关。

第 5 步：（可选）多设备批量接入

• 动作：对每台设备重复第 1 步与第 2 步。
• 判断：每台设备各生成一个投屏窗口。
• 结果：可逐台控制，也可同时操作全部设备（批量操作演示见 docs/ 内 group-control 动画）。

调整启动参数：config.ini 速查表

本节解决"改哪个参数"的问题。全部持久化参数集中于 config/config.ini，不修改时使用默认值即可。

规则：一次只修改一项并重启服务验证；出现画面异常时，优先回退UseDesktopOpenGL的取值再排查其余项。

编辑 keymap 按键映射 JSON

本节解决"用键鼠玩手游"的问题。映射文件为 JSON 格式，务必放入 keymap/ 目录才会被识别；仓库已内置游戏与短视频类脚本。完整编写规则见 docs/KeyMapDes_zh.md。

映射文件由两个核心结构组成：

1. switchKey：模式切换键。默认处于普通模式，按下此键进入自定义映射，再按一次退出。
2. keyMapNodes：按键映射数组。每个元素必须声明type，共五种取值：

执行流程：

• 动作：将新 JSON 放入keymap/，点击"刷新脚本"并选中，启动服务后点击"应用脚本"。
• 判断：鼠标左键单击时控制台输出pos值，直接取用该值写入坐标；坐标为相对值，屏幕宽高均以 1 归一。

• 结果：按~键切换进自定义映射模式，再按一次恢复普通控制；FPS 类游戏的载具须设置为单摇杆模式，否则方向盘映射失效。

编译 QtScrcpy：CMake 构建流程

本节解决"如何从源码构建"的问题，面向需要修改源码的开发者；直接使用发布二进制的用户跳过本节。

1. 准备 Qt 环境：安装 Qt 5.12 及以上（Windows 平台使用 MSVC 2019）；Arch Linux 执行pacman -S qt5-base qt5-multimedia qt5-x11extras。
2. 克隆源码：务必带上--recurse-submodules，项目包含第三方子模块：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qt/QtScrcpy

3. 执行编译：

• Windows：用 Qt Creator 打开根目录 CMakeLists.txt，构建 Release。
• Linux：终端执行

./ci/linux/build_for_linux.sh "Release"

4. 判断产物：编译结果位于output/x64/Release；运行后若报 shader 链接错误，按异常处理表"可控制但无画面"行处置。

异常处理：常见错误与处置方法

本节解决"出错了怎么办"的问题。按症状查表处置；仍无法解决时，先保留控制台日志再求助，避免空口描述。

完成验证：交付前逐项自检

全部步骤执行完毕后，按顺序自检；任一项不满足时，回到对应章节重做。

• 设备版本不低于 Android 5.0，USB 调试已开启，adb 版本唯一；
• 投屏窗口约 1 秒内出帧，帧率与清晰度符合启动配置；
• 点击、滚动、快捷键三类操作均正确透传（快捷键全表见 README_zh.md）；
• config.ini修改项已生效，控制台无持续报错；
• 需要键鼠映射时，脚本已加载且可用~键正常切换模式。

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