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

QtScrcpy 完整指南5 步连接 Android 投屏与键鼠控制【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpyQtScrcpy 是一款基于 Qt、OpenGL 与 FFmpeg 的 Android 实时投屏与控制工具可通过 USB 或 Wi-Fi 连接设备实现屏幕镜像显示、键鼠控制与屏幕录制且无需 root。本指南面向初次接触 QtScrcpy 的工程师与普通用户按序讲解环境准备、设备连接、config.ini 参数配置、keymap 按键映射、CMake 源码编译与常见异常处理。读完并执行完毕你应在 Windows、macOS 或 GNU/Linux 任一桌面平台独立完成投屏与控机操作。任务定位输入、输出与适用边界本节说明本文的交付物与适用范围避免读者投入时间后发现需求不匹配。项目内容输入一台 Android 设备API 21 / Android 5.0 及以上、一台桌面电脑Windows / macOS / GNU/Linux、一个已安装或可编译的 QtScrcpy输出一个正在运行的投屏窗口可键鼠控制、可录屏截图、可多设备批量连接覆盖范围连接流程、参数配置、按键映射、源码编译、异常处置不覆盖范围scrcpy-server 安卓端实现原理见 docs/DEVELOP.md约束与红线开始前必须遵守的 4 条规则本节列出操作中的硬性限制。违反任何一条都会导致连接失败、画面异常或设备状态被破坏。严禁在设备上 root 或安装任何应用。QtScrcpy 非侵入仅将服务端推送到设备/data/local/tmp目录运行。只允许电脑中存在一个 adb 版本。多版本并存时连接会被拒绝须先统一。严禁在程序命令行输入框执行阻塞命令如shell当前版本不支持。尽量不在多设备场景下将分辨率同时设为最大值批量投屏时应先调低分辨率与流畅度保证整体流畅。前置条件开始投屏前必须完成的 3 项检查本节解决环境没准备好的问题。以下三项逐项确认任一缺失都会导致找不到设备或无法控制。设备版本达标Android 系统不低于 5.0API 21。低于此版本服务无法启动。ADB 调试已开启在设备开发者选项中启用 USB 调试小米等机型须额外开启允许模拟点击否则会出现可见画面但无法控制。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不修改时使用默认值即可。参数默认值说明MaxFps0不限最大帧率仅 Android 10 及以上生效RenderExpiredFrames0是否渲染过期帧关闭可降低延迟UseDesktopOpenGL-1解码方式-1 自动、0 软解、1 dx 硬解、2 opengl 硬解ServerPath/data/local/tmp/scrcpy-server.jar服务端推送到设备的路径须以/结尾AdbPath空用系统默认自定义 adb 路径用于多 adb 版本冲突场景CodecName/CodecOptions空指定 H.264 编码器 / 编码参数规则一次只修改一项并重启服务验证出现画面异常时优先回退UseDesktopOpenGL的取值再排查其余项。编辑 keymap 按键映射 JSON本节解决用键鼠玩手游的问题。映射文件为 JSON 格式务必放入 keymap/ 目录才会被识别仓库已内置游戏与短视频类脚本。完整编写规则见 docs/KeyMapDes_zh.md。映射文件由两个核心结构组成switchKey模式切换键。默认处于普通模式按下此键进入自定义映射再按一次退出。keyMapNodes按键映射数组。每个元素必须声明type共五种取值type功能必备字段KMT_CLICK普通点击key、posKMT_CLICK_TWICE双击key、posKMT_CLICK_MULTI多次点击delay、posKMT_DRAG拖拽key、startPos、endPos、dragSpeedKMT_STEER_WHEEL方向盘4 键配合centerPos、四向按键及 offset执行流程动作将新 JSON 放入keymap/点击刷新脚本并选中启动服务后点击应用脚本。判断鼠标左键单击时控制台输出pos值直接取用该值写入坐标坐标为相对值屏幕宽高均以 1 归一。结果按~键切换进自定义映射模式再按一次恢复普通控制FPS 类游戏的载具须设置为单摇杆模式否则方向盘映射失效。编译 QtScrcpyCMake 构建流程本节解决如何从源码构建的问题面向需要修改源码的开发者直接使用发布二进制的用户跳过本节。准备 Qt 环境安装 Qt 5.12 及以上Windows 平台使用 MSVC 2019Arch Linux 执行pacman -S qt5-base qt5-multimedia qt5-x11extras。克隆源码务必带上--recurse-submodules项目包含第三方子模块git clone --recurse-submodules https://gitcode.com/GitHub_Trending/qt/QtScrcpy执行编译Windows用 Qt Creator 打开根目录 CMakeLists.txt构建 Release。Linux终端执行./ci/linux/build_for_linux.sh Release判断产物编译结果位于output/x64/Release运行后若报 shader 链接错误按异常处理表可控制但无画面行处置。异常处理常见错误与处置方法本节解决出错了怎么办的问题。按症状查表处置仍无法解决时先保留控制台日志再求助避免空口描述。症状处置方法adb server version ... doesnt match结束全部 adb 进程后重试或将config.ini的AdbPath指向当前使用的 adbUSB 连接后刷新列表为空先用第三方手机助手验证连接成功后再回到 QtScrcpy 刷新可见画面但无法控制在 USB 调试安全设置中开启允许模拟点击画面不清晰Windows 在程序属性中设置由应用程序执行缩放或放大视频窗口Could not open video stream在启动配置中选择一个较低的分辨率后重试可控制但无画面shader program is not linked将config.ini中UseDesktopOpenGL改为 1 或 2无法输入中文设备端安装搜狗或 QQ 输入法完成验证交付前逐项自检全部步骤执行完毕后按顺序自检任一项不满足时回到对应章节重做。设备版本不低于 Android 5.0USB 调试已开启adb 版本唯一投屏窗口约 1 秒内出帧帧率与清晰度符合启动配置点击、滚动、快捷键三类操作均正确透传快捷键全表见 README_zh.mdconfig.ini修改项已生效控制台无持续报错需要键鼠映射时脚本已加载且可用~键正常切换模式。【免费下载链接】QtScrcpyAndroid real-time display control software项目地址: https://gitcode.com/GitHub_Trending/qt/QtScrcpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考