> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Android 环境配置

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

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

## 通过 adb 连接设备 {#connect-device}

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

### 安装 adb

- 通过 [Android Studio](https://developer.android.com/studio) 或独立的 [Android 命令行工具](https://developer.android.com/studio#command-line-tools-only)安装 `adb`。
- 在终端运行以下命令，验证 `adb` 是否安装成功：

```bash
adb --version
```

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

```log
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 环境变量文档](https://developer.android.com/tools/variables)配置 `ANDROID_HOME` 环境变量，并检查是否生效：

```bash
echo $ANDROID_HOME
```

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

```log
/Users/your_username/Library/Android/sdk
```

### 开启调试并连接设备

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

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

![android usb debug](/images/android-usb-debug-en.png)

### 确认设备连接 {#verify-device-connection}

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

```bash
adb devices -l
```

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

```log
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` 后再继续后续步骤。

## 验证 {#verify}

`adb devices -l` 中的目标设备状态为 `device` 后，在 Playground 中验证环境。打开[开始使用](/zh/get-started.md?platform=android\&scene=playground)，页面已为你选好 Android 和 Playground，选择模型接入方式后，按步骤执行一次 `aiAct` 操作和一次 `aiAssert` 断言。断言通过即表示 adb 连接、屏幕截图、触控输入和模型调用都正常。

## 常见问题

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

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

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

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

```text
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 调试（安全设置）** 或 **禁止权限监控**（如有）

![android usb debug](/images/android-usb-debug.png)

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

如果文本已正常填入，但在软键盘收起时消失，通常是输入框响应了收起键盘时发送的 `ESC` 按键事件。你可以通过调整键盘收起策略解决该问题，具体参数与示例见 [Android JavaScript SDK](/zh/sdk/android.md#输入文本后输入框内容被清空或消失)。

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

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

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

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

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

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

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

### 如何配置 scrcpy 视频码率？

请参阅 [Android JavaScript SDK](/zh/sdk/android.md#如何配置-scrcpy-视频码率)。

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

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

```bash
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` 指定监听地址。

:::warning 安全提示
scrcpy 投屏服务目前不包含会话鉴权机制。开启远程监听后，任何能够访问该端口的客户端均可读取设备信息与实时屏幕画面。请仅在受信任的内网环境中开启，并通过防火墙限制可访问的客户端范围。
:::

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

请参阅 [Android JavaScript SDK](/zh/sdk/android.md#adb-connection-options)。