Escrcpy 使用指南：基于图形化 Scrcpy 的 Android 设备显示与控制全解析

Escrcpy 使用指南：基于图形化 Scrcpy 的 Android 设备显示与控制全解析

【免费下载链接】escrcpy📱 Display and control your Android device graphically with scrcpy.项目地址: https://gitcode.com/GitHub_Trending/es/escrcpy

本篇技术指南围绕 Escrcpy 的官方中文文档（README-CN.md）展开，系统讲解这款基于 Electron 的 Scrcpy 图形化客户端如何实现 Android 设备的镜像显示、多设备控制、无线连接与反向网络共享。读完本文，你将掌握 Escrcpy 的安装方式、USB/无线连接流程、核心特性背后的实现原理、偏好设置与快捷键体系，并能在多设备场景下组合使用群控、窗口编排与自动化能力。

Escrcpy 是一款以「图形化 Scrcpy」为定位的开源桌面应用，本质是把命令行形态的 Scrcpy 封装为可视化界面，同时叠加 ADB 设备管理、多设备协同、MCP 自动操控等能力。项目采用 Electron + Vue 3 构建（版本信息见 desktop/package.json），围绕 Scrcpy 内核形成了完整的设备接入、镜像控制、文件管理与自动化工作流。下面从特性概览、安装连接、操作实践到源码原理逐层展开。

核心特性一览

README 文档归纳了 Escrcpy 的十项核心能力，这也是理解整个项目功能边界的起点：

• 内嵌镜像：独立内嵌窗口，自动适配分辨率与屏幕方向，内置一体化快捷操作；
• 键盘映射：直接在内嵌镜像上配置点击、摇杆、滑动、滚动与自动化映射；
• 多设备群控：单窗口同控多台设备，广播输入，支持批量截图与 APK 安装；
• 集成控制栏：可拖拽排序的紧凑侧边栏，涵盖旋转、截图、应用、文件、终端、自动操控与自动化；
• 自动操控：基于 MCP 协议深度融合构建，支持多模型对话与智能设备控制；
• 自动化脚本：图形化逐步编排工作流，支持屏幕识图条件判断与多设备批量执行；
• 多设备管理：可视化窗口编排，统一管理所有已连接设备；
• 无线连接：无线 ADB 连接，支持局域网自动发现与 Gnirehtet 反向供网；
• 快捷键管理：可自定义的全局快捷键，快速执行设备操作；
• Scrcpy 内核：高性能、低延迟屏幕镜像与控制。

需要说明的是，README 同时指出：Escrcpy 专注于稳定的集成底座能力，部分高级特性源自私有扩展仓库 EscrcpyX，以付费形式提供。本文仅覆盖开源仓库中可验证的能力。

技术底座：Electron 与 Scrcpy 内核的融合

从 desktop/package.json 的依赖清单可以看出项目的技术选型：electron33 提供桌面容器，vue3.5 负责界面，@devicefarmer/adbkit封装 ADB 协议，@escrcpy/shared等 workspace 包承载共享逻辑。开发脚本支持pnpm dev启动开发服务器、pnpm build构建应用。

Scrcpy 内核的接入方式值得关注。desktop/electron/middleware/scrcpy/index.js 中，所有镜像能力都通过sheller以scrcpy <command>子进程形式拉起：

mirrorProcess = sheller(`scrcpy ${command}`, { shell: true, encoding: 'utf8', ... })

该中间件围绕 Scrcpy 命令行封装了一组能力函数，与界面的各类操作一一对应：

其中launch的实现值得展开：当启用新显示器（--new-display）时，它会通过正则/New display:.+?\(id=(\d+)\)/i从 scrcpy 输出中解析出虚拟显示器 ID 作为启动完成的信号，从而在界面层获得「新显示器已就绪」的可靠回调（desktop/electron/middleware/scrcpy/index.js#L222-L231）。所有子进程统一由ProcessManager管理，在应用退出前统一 kill，避免残留进程（见quit-before事件监听）。

安装方式

通过发布的软件包手动安装

Escrcpy 支持 Windows、macOS、Linux 三大桌面平台，各平台均可从项目的发布页下载对应安装包（GitHub 发布页及 Gitee/GitCode 国内镜像源均提供分发，详见 快速上手文档）。

macOS 通过 Homebrew 安装

macOS 用户可使用 Homebrew 安装，具体方法参阅官方维护的 homebrew-escrcpy 仓库（见 README-CN.md 安装章节）。

开发模式运行

开发者可克隆仓库后以开发模式运行：

git clone <仓库地址> cd escrcpy corepack enable pnpm pnpm install pnpm dev

其中pnpm dev启动 Vite 开发服务器，pnpm build会根据当前平台自动构建安装包（详见 develop.md）。

快速上手：USB 连接与无线连接

USB 连接方式

1. 在安卓设备上启用「开发者模式」和「USB 调试」功能；
2. 启动 Escrcpy 并将安卓设备通过 USB 连接电脑；
3. Escrcpy 设备列表应已检测到设备，点击「开始镜像」；
4. 开始使用。

注意：若手机弹出调试授权提示，请点击允许。

无线连接：扫码连接

1. 先完成 USB 连接方式的前两步；
2. 在开发者选项中启用并进入「无线调试」；
3. 点击「通过二维码配对设备」；
4. 开始使用。

扫码连接背后对应 ADB 的pair命令。在 desktop/electron/middleware/adb/index.js 中可以看到其实现：通过adb pair <host>:<port> <code>完成无线配对，若 stderr 非空则判定配对失败并抛出。

无线连接：IP 地址连接

注意：若首次无线连接失败，可能需先进行无线配对；需在无线调试页面获取设备无线地址（通常为连接 WiFi 时分配的 IP 地址）和端口号（默认为 5555）。

1. 先完成 USB 连接方式的前两步；
2. 在 Escrcpy 中输入设备 IP 地址和端口号，点击「连接设备」；
3. 此时设备列表应显示您的手机，点击「开始镜像」；
4. 开始使用。

对应的connect实现（desktop/electron/middleware/adb/index.js#L365-L381）不仅检查 stderr，还会检测 stdout 中是否包含cannot、failed等错误关键词，以提高连接失败的判定准确性。

局域网自动发现

除了手动输入 IP，Escrcpy 还支持通过 mDNS 在局域网内自动发现支持无线调试的设备。从源码看，该流程分三步执行（desktop/electron/middleware/adb/index.js#L233-L343）：

1. scanMdnsDevices：基于 mDNS 广播扫描候选设备；
2. probeDeviceCandidates：对候选设备逐一探测 ADB 端口可达性；
3. 过滤已连接设备后，通过connect批量接入，并发数受偏好设置中的「并发上限」控制。

整个过程会通过onStatus回调向界面反馈discovering / probing / unreachable / connecting / connected / error等状态，这也是界面上「发现设备」进度提示的来源。

macOS 与 Linux 平台的注意点

macOS 和 Linux 平台未预装 Scrcpy，需要手动安装，具体分别参考 Linux 安装文档 与 macOS 安装文档。依赖安装成功后，即可按照上述 USB 或无线连接步骤操作。

设备操作与多设备群控

操作指南 将设备操作归纳为三大类：

批量处理

• 批量镜像
• 批量截屏
• 批量安装应用
• 批量文件管理
• 批量执行脚本
• 批量计划任务

批量能力是「单窗口同控多台设备」的落地点。批量截屏在 ADB 中间件中通过screencap实现（desktop/electron/middleware/adb/index.js#L108-L122）：使用 adbx 的screenshot.capture抓取屏幕，文件按Screencap-YYYY-MM-DD-HH-mm-ss.png命名写入偏好设置中配置的存储路径（默认桌面）。

控制模式

• 镜像模式（对应mirror）
• 录制模式（对应record）
• 摄像头录制
• 音频录制
• 摄像头
• 自定义模式（透传自定义 Scrcpy 参数）
• OTG 模式

「自定义模式」直接对应用户在偏好设置中填写的额外 Scrcpy 参数，最终拼入createMirrorProcess的--serial与--window-title之后的命令行（desktop/electron/middleware/scrcpy/index.js#L112-L120）。

设备交互栏

• 自动操控（MCP）
• 切换应用、返回主页、返回键
• 启动应用、关闭屏幕（实验性功能）
• 通知中心、电源键
• 屏幕旋转、音量控制、截图
• 重启设备、安装 APP、文件管理器、执行脚本、计划任务
• Gnirehtet（反向网络共享）

交互栏的实现位于 控制栏组件 及其子组件（explorer、gnirehtet、install、launch、rotation、screenshot、terminal、volume 等），支持拖拽排序。

偏好设置详解

Escrcpy 将 Scrcpy 的命令行参数图形化为偏好设置界面（偏好设置文档），并按功能域分组。每组配置项最终都会转换成对应的 scrcpy 命令行参数拼接进进程启动命令。

通用

主题风格、语言选择、文件存储路径、ADB 路径、Scrcpy 路径、Gnirehtet 路径、Scrcpy 参数、Gnirehtet 参数、自动连接设备、自动执行镜像、Gnirehtet 修复、调试模式、悬浮控制栏、使用系统终端、首选终端、并发上限。

其中「ADB 路径」的动态切换在源码中有专门处理：当common.adbPath配置变化时，中间件会先 kill 现有客户端与子进程，再重新初始化 ADB 客户端（desktop/electron/middleware/adb/index.js#L38-L58），保证运行期切换不残留旧连接。

视频

禁用视频传输、最大分辨率、视频比特率、刷新频率、视频编解码器、显示方向、旋转角度、屏幕裁剪、显示器选择、视频缓冲区、接收端（v4l2）缓冲区。

设备

显示触摸点、保持唤醒状态、控制时关闭屏幕、控制结束后关闭屏幕、禁用控制时自动亮屏、模拟辅助显示器。

窗口

窗口宽度、窗口高度、窗口 X 坐标、窗口 Y 坐标、无边框模式、全屏模式、窗口置顶、禁用屏幕保护。

音频

禁用音频传输、保留设备音频、音频源选择、音频编解码器、音频比特率、音频缓冲区、音频输出缓冲区。

录制

录制视频格式、录制视频方向、录制时长、禁用视频回放、禁用音频回放。

输入

鼠标模式、鼠标绑定、键盘模式、键盘注入方式、游戏手柄设置。

摄像

摄像头源选择、摄像头尺寸、摄像头比例、摄像头帧率。

这些配置项在代码侧以「配置模型」形式组织。以启动类配置为例，desktop/src/models/preference/launch/index.js 定义了--new-display（虚拟显示器，内置从 1280x720 到 7680x4320 的桌面/平板/手机/超宽屏等几十种常见分辨率模板）、--display-ime-policy、--flex-display、--no-vd-destroy-content等字段，每个字段都声明了对应的field参数名、控件类型（Select/Switch）与默认值。这种「模型驱动表单」的设计，让新增配置项只需要添加模型描述即可自动生成界面。

快捷键参考

在 scrcpy 窗口内可以通过键盘和鼠标快捷键执行操作。以下列表中，MOD是快捷键修饰键，默认是（左）Alt或（左）Super（Super通常是 Windows 或 Cmd 键）。

可以使用--shortcut-mod修改修饰键，可选键包括lctrl、rctrl、lalt、ralt、lsuper和rsuper：

# 使用右Ctrl作为快捷键修饰键 scrcpy --shortcut-mod=rctrl # 使用左Ctrl或左Super作为快捷键修饰键 scrcpy --shortcut-mod=lctrl,lsuper

完整快捷键表（来源：快捷键文档）：

¹ 双击黑边以去除它们。² 右键点击会在屏幕关闭时唤醒屏幕，否则执行 BACK 操作。³ 第 4 和第 5 鼠标按键（如果鼠标支持）。⁴ 对于开发中的 React Native 应用，MENU会触发开发菜单。⁵ 仅在 Android 7 及以上版本支持。

重复按键的快捷键需要在释放后再次按下该键来执行。例如执行「展开设置面板」：先按下并保持按住MOD，然后双击n，最后释放MOD。所有Ctrl+按键的快捷键会被转发到设备，由当前活动应用处理。

Gnirehtet 反向网络共享

反向网络共享允许 Android 设备使用所连接计算机的网络连接，不需要任何 root 权限（设备或计算机均无需），支持 GNU/Linux、Windows 和 Mac OS。目前通过 IPv4 转发 TCP 和 UDP 流量，不支持 IPv6（详见 Gnirehtet 参考文档）。

Windows 和 Linux 应用已内置 Gnirehtet 功能；设备连接成功后，通过「设备」→「设备控制栏」→「Gnirehtet」即可启用反向网络功能。macOS 版本未内置 Gnirehtet，需手动安装（安装指南）。

Gnirehtet 在源码中同样以子进程方式管理（desktop/electron/middleware/gnirehtet/index.js）。其完整启用流程run(deviceId)可分为四步（desktop/electron/middleware/gnirehtet/index.js#L86-L114）：

1. stop：先清理可能存在的旧进程；
2. relay：启动中继服务器，并监听 stdout 中的Relay server started作为启动成功的信号；
3. isInstalled：通过 ADB 检查设备端是否已安装com.genymobile.gnirehtet（偏好设置中的「Gnirehtet 修复」开启时跳过检查）；
4. install+start：未安装则先安装 APK，再启动客户端，启动时还会追加偏好设置中「Gnirehtet 参数」配置的附加参数。

窗口编排：多设备可视化布局

设备窗口编排是 Escrcpy 面向多设备管理和屏幕空间优化的高级功能（详见 窗口编排文档），通过全屏的可视化拖拽界面，可精确控制每个设备窗口的位置、大小与布局。

核心组件

• 全局配置组件：设置所有设备的默认窗口参数（默认宽度/高度、位置坐标等），每个编排方案中只能有一个；
• 设备窗口组件：每个已连接设备可添加为独立组件，支持独立位置尺寸设置，可继承或覆盖全局配置。

设备显示规则：只显示当前已连接的设备；已添加的设备不会重复显示；设备名称优先显示自定义名称，其次为设备型号。

布局调整要点

• 移动：点击窗口组件后按住鼠标左键拖拽，松手完成定位；
• 缩放：拖拽窗口边角调整大小，系统自动维持合理比例；
• 尺寸限制：最小宽度为容器宽度的 1/6，最小高度为容器高度的 1/4；窗口不能拖拽到编排区域外部；允许重叠但建议避免完全遮挡。

配置保存机制

• 全局配置存储在scrcpy.global配置节点，设备配置存储在scrcpy.[设备ID]节点；
• 参数格式对应--window-width、--window-height、--window-x、--window-y；
• 配置应用时机：启动镜像时自动应用对应窗口配置；设备特定配置优先，未设置的参数继承全局配置；保存后立即生效，无需重启应用。

开发与生态

开发者指南

开发者可参阅 develop.md：要求 Node.js v20+ 与 Git，使用 pnpm 管理依赖。构建命令支持按平台分别产出安装包（pnpm build:win/build:mac/build:linux）。调试时可开启偏好设置中的「调试模式」，并使用Ctrl+Shift+I打开 DevTools。

项目技术栈与致谢

README 中特别致谢了该项目所依赖的开源生态：scrcpy（屏幕镜像与控制核心）、adbkit（ADB 协议工具库）、electron（桌面框架）、vue（前端框架）、gnirehtet（反向网络共享）、yadb（增强 ADB 命令：快速输入、截图、剪贴板）等。

从代码组织看，项目采用 monorepo 结构（pnpm-workspace.yaml），将可复用能力拆分为独立包：packages/adbx（ADB 扩展）、packages/electron-ipcx（Electron 进程通信）、packages/electron-setup（应用装配）、packages/shared（共享工具）、packages/unocss-preset-shades（主题预设）。主应用位于 desktop 目录，其中desktop/electron承载主进程与各类中间件，desktop/src承载 Vue 渲染进程，文档位于 docs 目录（中英文双语）。

后续路线

项目的后续规划与里程碑可查阅 milestones 文档，常见问题可参考 帮助文档。作为开源项目，其更新节奏不固定，遇到问题可通过 Issues 反馈。

【免费下载链接】escrcpy📱 Display and control your Android device graphically with scrcpy.项目地址: https://gitcode.com/GitHub_Trending/es/escrcpy