QtScrcpy

Windows MacOS Ubuntu

许可证

中文用户？点我查看中文介绍

QtScrcpy 支持通过 USB 或网络显示和控制 Android 设备。它不需要 root 权限。

它支持三大主要平台：GNU/Linux、Windows 和 macOS。

它专注于：

轻量级（仅显示设备屏幕）
性能（30~60 fps）
质量（1920×1080 或更高）
低延迟（35~70ms）
快速启动（仅需约 1 秒即可显示第一帧）
非侵入性（设备上不会安装任何东西）

win

mac

linux

按键映射

您可以根据需要编写脚本，将键盘和鼠标操作映射到手机的触摸和点击。这里是脚本编写规则。

默认提供了抖音和一些其他游戏的脚本。启用后，您可以用键盘和鼠标玩游戏。PUBG Mobile 的默认按键映射如下：

这里有一个玩 PUBG Mobile 的视频演示。

添加新的自定义映射文件的说明。

编写自定义脚本并将其放入 keymap 目录
点击 刷新脚本 显示它
选择你的脚本
连接手机，启动服务并点击 应用
按 ~ 键（按键映射脚本中的 SwitchKey）切换到自定义映射模式
再次按 ~ 键切换回正常模式
（对于 PUBG Mobile 等游戏）如果你想用方向盘键移动车辆，需要将移动模式设置为 单摇杆模式。

群控

你可以同时控制所有手机。

群控演示

致谢

QtScrcpy 基于 Genymobile 的 scrcpy 项目。非常感谢！

QtScrcpy 与原始 scrcpy 的区别如下：

关键点	scrcpy	QtScrcpy
界面	sdl	qt
视频编码	ffmpeg	ffmpeg
视频渲染	sdl	opengl
跨平台	自行实现	由 Qt 提供
语言	C	C++
风格	同步	异步
按键映射	无自定义按键映射	支持自定义按键映射
构建	meson+gradle	qmake 或 CMake

使用 Qt 可以很容易地自定义 GUI
基于 Qt 的信号槽机制的异步编程提高了性能
易于学习
增加了多点触控支持

学习

如果你对它感兴趣并想学习它是如何工作的，但不知道如何入手，你可以选择购买我录制的视频课程。它详细介绍了整个软件的开发架构和开发过程，帮助你从零开始开发 QtScrcpy。

课程介绍：https://blog.csdn.net/rankun1/article/details/87970523

你可以加入我的 QtScrcpy QQ 群，与志同道合的朋友交流想法。

QQ 群号：901736468

要求

Android API >= 21（Android 5.0）。

确保你在设备上启用了 ADB 调试。

下载

Windows

为了简便起见，在 Windows 上，预构建的包含所有依赖项（包括 ADB）的压缩包可在 Releases 中获取：

[QtScrcpy][github-download]

或者您可以自行构建

Mac OS

为了简便起见，在 Mac OS 上，预构建的包含所有依赖项（包括 ADB）的压缩包可在 Releases 中获取：

[QtScrcpy][github-download]

或者您可以自行构建

Linux

对于 Arch Linux 用户，您可以使用 AUR 安装：yay -Syu qtscrcpy（可能过时；维护者：yochananmarqos）

对于其他发行版的用户，您可以从 Releases 获取预构建的压缩包：

[QtScrcpy][github-download]

或者您可以在 GitHub Actions 中获取，在 dev 分支下载最新的构建产物。

或者您可以自行构建（不推荐，如果可以的话请从 Actions 获取）

运行

将您的 Android 设备连接到计算机，然后运行程序并点击 USB 连接 或 WiFi 连接

无线连接步骤（确保手机和电脑在同一局域网内）：

在 Android 设备的开发者选项中启用 USB 调试
通过 USB 将 Android 设备连接到计算机
点击更新设备，您将看到设备号已更新
点击获取设备 IP
点击启动 adbd
点击无线连接
再次点击更新设备，将发现另一个带有 IP 地址的设备。选择此设备。
点击启动服务

注意：在启动 adbd 后，无需继续保持 Android 设备通过 USB 连接。

界面按钮介绍：

启动配置：启动服务前的功能参数设置

您可以设置本地录制视频的比特率、分辨率、录制格式和视频保存路径。
- 后台录制：启动服务后不显示 Android 设备屏幕。在后台进行录制。
- 总是置顶：Android 设备的视频窗口将始终保持在顶部
- 关闭屏幕：启动服务后自动关闭 Android 设备屏幕以节省电量
- 反向连接：服务启动模式。如果遇到连接失败并提示 more than one device，可以取消勾选
刷新设备：刷新当前连接的设备
启动服务：连接到 Android 设备
停止服务：断开与 Android 设备的连接
停止所有服务：断开所有已连接的 Android 设备
获取设备 IP：获取 Android 设备的 IP 地址并更新到"无线"区域，方便无线连接设置。
启动 adbd：启动 Android 设备的 adbd 服务。在无线连接前必须启动它。
无线连接：无线连接到 Android 设备
无线断开：断开无线连接的 Android 设备
adb 命令：执行自定义 ADB 命令（目前不支持阻塞命令，如 shell）

主要功能

实时显示 Android 设备屏幕
实时鼠标和键盘控制 Android 设备
屏幕录制
截图为 png
无线连接
支持多设备连接
全屏显示
显示在顶部
安装 apk：将 apk 拖放到视频窗口以安装
传输文件：将文件拖放到视频窗口以发送文件到 Android 设备
后台录制：仅录制，不显示界面
复制粘贴

可以在计算机和设备之间双向同步剪贴板：
- Ctrl + c 将设备剪贴板复制到计算机剪贴板；
- Ctrl + Shift + v 将计算机剪贴板复制到设备剪贴板；
- Ctrl + v 将计算机剪贴板作为一系列文本事件粘贴（非 ASCII 字符尚不支持）。
群控
将设备扬声器声音同步到计算机（基于 sndcpy，仅支持 Android 10+）

快捷键

操作	快捷键 (Windows)	快捷键 (macOS)
切换全屏模式	`Ctrl`+`f`	`Cmd`+`f`
将窗口调整为 1:1（像素完美）	`Ctrl`+`g`	`Cmd`+`g`
调整窗口大小以移除黑边	`Ctrl`+`w` \| 双击¹	`Cmd`+`w` \| 双击¹
点击 `HOME`	`Ctrl`+`h` \| 中键点击	`Ctrl`+`h` \| 中键点击
点击 `BACK`	`Ctrl`+`b` \| 右键点击²	`Cmd`+`b` \| 右键点击²
点击 `APP_SWITCH`	`Ctrl`+`s`	`Cmd`+`s`
点击 `MENU`	`Ctrl`+`m`	`Ctrl`+`m`
点击 `VOLUME_UP`	`Ctrl`+`↑` (上)	`Cmd`+`↑` (上)
点击 `VOLUME_DOWN`	`Ctrl`+`↓` (下)	`Cmd`+`↓` (下)
点击 `POWER`	`Ctrl`+`p`	`Cmd`+`p`
开机	右键点击²	右键点击²
关闭设备屏幕（保持镜像）	`Ctrl`+`o`	`Cmd`+`o`
展开通知面板	`Ctrl`+`n`	`Cmd`+`n`
收起通知面板	`Ctrl`+`Shift`+`n`	`Cmd`+`Shift`+`n`
复制到剪贴板³	`Ctrl`+`c`	`Cmd`+`c`
剪切到剪贴板³	`Ctrl`+`x`	`Cmd`+`x`
同步剪贴板并粘贴³	`Ctrl`+`v`	`Cmd`+`v`
注入计算机剪贴板文本	`Ctrl`+`Shift`+`v`	`Cmd`+`Shift`+`v`
¹双击黑色边框可将其移除。

²右键点击可在屏幕关闭时开启屏幕,否则会执行返回操作。

³仅适用于 Android 7.0 及以上版本。

待办事项

常见问题

开发

欢迎大家参与维护本项目并贡献代码,但请遵循以下要求:

请向 dev 分支而非 master 分支提交 PR
提交 PR 前请先 rebase 原项目
请遵循"小批量、多次数"的原则提交 PR(建议一个改动一个 PR)
请保持代码风格与现有风格一致

为什么开发 QtScrcpy?

以下是按重要性排序的几个原因。

在学习 Qt 的过程中,我需要一个实际项目来尝试。
我有一些音视频方面的背景技能,并且对此感兴趣。
我有一些 Android 开发技能。但已经很久没用了,想巩固一下。
我发现了 scrcpy,决定用新的技术栈(C++ + Qt + Opengl + FFmpeg)重新制作它。

构建

所有依赖都已提供,编译起来很简单。

QtScrcpy

非 Arch Linux 用户

使用官方 Qt 安装程序或第三方工具如 aqt 在目标平台上设置 Qt 开发环境。需要 Qt 5.12 及以上版本。(Windows 上使用 MSVC 2019)
使用 git clone --recurse-submodules git@github.com:barry-ran/QtScrcpy.git 克隆项目
对于 Windows,用 QtCreator 打开 CMakeLists.txt 并编译 Release 版本
对于 Linux,直接运行 ./ci/linux/build_for_linux.sh "Release" 注意:编译后的文件位于 output/x64/Release

Arch Linux 用户

安装软件包: base-devel cmake qt5-base qt5-multimedia qt5-x11extras (推荐 qtcreator)
使用 git clone --recurse-submodules git@github.com:barry-ran/QtScrcpy.git 克隆项目
运行 ./ci/linux/build_for_linux.sh "Release"

Scrcpy-Server

在目标平台上搭建 Android 开发环境
用 Android Studio 打开项目根目录中的 server 项目
首次打开时,如果没有对应版本的 Gradle,会提示查找 Gradle,是否升级 Gradle 或创建。选择取消。取消后会提示选择现有 Gradle 的位置。也取消,它会自动下载。
编译 apk 后,将其重命名为 scrcpy-server 并替换 QtScrcpy/QtScrcpyCore/src/third_party/scrcpy-server。

许可证

由于基于 scrcpy,因此使用与 scrcpy 相同的许可证

Copyright (C) 2025 Rankun

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.