#Android 环境配置

Midscene 通过 adb 连接并控制 Android 设备，支持对原生应用、混合应用及系统界面进行自动化操作。

本文介绍如何准备 Android 环境：安装 adb 并连接设备。Playground、Midscene Test 和 JavaScript SDK 都使用同样的连接。

#通过 adb 连接设备

运行 Midscene 的电脑需要通过 adb 连接目标 Android 设备，支持 USB 和无线 adb 两种连接方式。如果已安装 adb 并连接好设备，可直接跳至确认设备连接。

#安装 adb

• 通过 Android Studio 或独立的 Android 命令行工具安装 adb。
• 在终端运行以下命令，验证 adb 是否安装成功：

adb --version

输出类似以下内容即表示安装成功：

Android Debug Bridge version 1.0.41
Version 34.0.4-10411341
Installed as /usr/local/bin/adb
Running on Darwin 24.3.0 (arm64)

• 参考 Android 环境变量文档配置 ANDROID_HOME 环境变量，并检查是否生效：

echo $ANDROID_HOME

输出应指向本机安装的 Android SDK 目录，例如：

/Users/your_username/Library/Android/sdk

#开启调试并连接设备

以下以 USB 连接为例；如果设备已通过无线 adb 连接，可继续使用现有连接。

1. 在手机系统设置的「开发者选项」中开启 USB 调试（若同时存在 USB 调试（安全设置），请一并开启，以确保支持触控事件注入）。
2. 使用支持数据传输的 USB 数据线将手机连接到电脑。
3. 保持手机解锁亮屏，在手机弹出的授权窗口中勾选并允许 USB 调试。

#确认设备连接

在终端运行以下命令检查连接状态：

adb devices -l

输出中设备状态显示为 device 即表示连接就绪：

List of devices attached
s4ey59	device usb:34603008X product:cezanne model:M2006J device:cezan transport_id:3

如果同时连接了多台设备，请记录目标设备所在行第一列的设备 ID（如上例中的 s4ey59），以便后续在 Playground 或项目配置中指定该设备。

若未显示目标设备或状态不是 device，请按以下情况排查：

• 列表为空：USB 连接请检查数据线（需支持数据传输）、USB 连接模式和 USB 调试开关；无线连接请检查网络及 adb connect 连接状态。
• unauthorized：请解锁手机屏幕，在手机弹出的授权窗口中勾选并允许 USB 调试。
• offline：请重新建立 USB 或无线 adb 连接，必要时重启 adb 服务。请确认设备状态变为 device 后再继续后续步骤。

#验证

adb devices -l 中的目标设备状态为 device 后，在 Playground 中验证环境。打开开始使用，页面已为你选好 Android 和 Playground，选择模型接入方式后，按步骤执行一次 aiAct 操作和一次 aiAssert 断言。断言通过即表示 adb 连接、屏幕截图、触控输入和模型调用都正常。

#常见问题

#找不到设备，或设备显示为未授权、离线

运行 adb devices -l，参照确认设备连接中的排查说明检查数据线、USB 调试授权与连接状态。请先确保目标设备状态显示为 device，再排查截图或触控问题。

#设备已连接，为什么仍然无法控制（报错 INJECT_EVENTS）？

如果执行点击或滑动时遇到类似以下的权限报错：

Error:
Exception occurred while executing 'tap':
java.lang.SecurityException: Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.

这通常是因为部分品牌手机（如小米 / Redmi / VIVO / OPPO 等）对模拟点击有独立的权限开关。请在系统设置的「开发者选项」中确认以下两项均已开启：

1. USB 调试
2. USB 调试（安全设置） 或 禁止权限监控（如有）

#输入文本后，输入框内容被清空或消失

如果文本已正常填入，但在软键盘收起时消失，通常是输入框响应了收起键盘时发送的 ESC 按键事件。你可以通过调整键盘收起策略解决该问题，具体参数与示例见 Android JavaScript SDK。

#英文文本被 Android 输入法改写

请先对比执行报告中记录的输入内容与输入框内的实际文本。若报告中的参数无误，但实际输入出现字符乱序、漏字或被拼音输入法候选词截获，请检查手机当前输入法及自动纠错设置。有关输入通道的详细说明，请参阅 Android JavaScript SDK。

#安全页面（如密码输入框）截图黑屏

请先切换到普通页面测试截图是否正常。如果仅在密码输入页或敏感信息页出现黑屏，通常是应用开启了系统截屏保护（FLAG_SECURE），并非 adb 连接断开。有关截图机制与限制说明，请参阅 Android JavaScript SDK。

#为什么 scrcpy 会回退到 ADB 截图？

为避免模型基于过期画面做出错误决策，Midscene 会严格校验 scrcpy 视频帧的时间戳：任何无法证明采集时间晚于最近一次已完成操作、或超出最大帧龄限制的视频帧都会被拒绝。如果当前 scrcpy 视频流未能及时提供有效新帧，Midscene 会自动重启一次 scrcpy；仅当重启后仍无法获取有效帧时，才会回退为 adb 截图。

部分 Android 硬件编码器在屏幕画面完全静止时会暂停输出新帧，或者在视频流刚启动、USB 传输抖动时也可能触发该现象。注意：出现帧新鲜度超时告警并不代表传输带宽不足或视频码率过高，请勿仅因看到该告警就盲目调整视频码率。

#如何配置 scrcpy 视频码率？

请参阅 Android JavaScript SDK。

#如何从局域网其他电脑远程访问 Android Playground？

出于安全考虑，Playground 服务与内置的 scrcpy 投屏服务默认均只监听本机回环地址 127.0.0.1。如果需要从局域网内的另一台电脑访问 Android Playground，需在启动时通过环境变量显式放开两者的监听地址（以 macOS / Linux 为例）：

MIDSCENE_PLAYGROUND_HOST=0.0.0.0 MIDSCENE_SCRCPY_HOST=0.0.0.0 pnpm dlx @midscene/android-playground

启动后，在客户端浏览器中访问服务端电脑的实际局域网 IP（或主机名）加上终端打印的 Playground 端口（注意：0.0.0.0 是服务端监听通配地址，不能直接填在浏览器地址栏中），并确保防火墙已放行 Playground 与 scrcpy 两个端口。

MIDSCENE_SCRCPY_HOST 仅作用于独立的 Android Playground CLI，也可直接设为服务端具体的网卡 IP（如 192.168.1.100，此时本机自动打开的预览页也会使用该 IP 连接投屏流）。若在代码中直接实例化 ScrcpyServer，可通过构造函数参数 host 指定监听地址。

#如何使用自定义的 adb 路径或连接远程 adb 服务？

请参阅 Android JavaScript SDK。