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

# iOS 环境配置

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

本文介绍如何准备 iOS 环境：构建并启动 WDA，让运行 Midscene 的电脑可以访问它。Playground、Midscene Test 和 JavaScript SDK 都使用同样的连接。

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

Midscene 通过运行中的 WebDriverAgent（WDA）服务与 iOS 真机或模拟器通信。如果 WDA 服务已启动且可从当前电脑访问，可直接跳至[确认 WDA 服务状态](#verify-wda-status)。

### 构建并启动 WebDriverAgent

开始前，请先准备好以下 iOS 开发环境：

- macOS（iOS 开发与真机调试必需）
- Xcode 及 Xcode 命令行工具（Command Line Tools）
- iOS 模拟器或真机设备

:::info 版本要求

WebDriverAgent 版本须 **>= 7.0.0**。

:::

请参考 Appium 官方文档完成 WebDriverAgent（WDA）的构建与启动：

- **模拟器配置**：[Run Prebuilt WDA](https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda/)
- **真机配置**：[Real Device Configuration](https://appium.github.io/appium-xcuitest-driver/latest/getting-started/device-setup/)

### 配置真机并转发端口

iOS 模拟器会直接在 `localhost` 上监听端口，无需转发；如果使用模拟器或已配置好的远程 WDA 服务，可跳至[确认 WDA 服务状态](#verify-wda-status)。

使用 iOS 真机时：

1. 使用 USB 数据线将手机连接到 Mac，并在手机弹窗中点击「信任此电脑」。
2. 在手机系统设置中开启**开发者模式**（「设置 > 隐私与安全性 > 开发者模式」）与 **UI Automation**（「设置 > 开发者 > Enable UI Automation」）。
3. 完成开发者证书签名并在真机上启动 WDA 后，使用 `iproxy`（可通过 `brew install libimobiledevice` 安装）将设备上的 WDA 端口（默认为 `8100`）转发到 Mac 本机：

```bash
iproxy 8100 8100 YOUR_DEVICE_ID
```

请将 `YOUR_DEVICE_ID` 替换为真机的实际 UDID，并保持 WDA 与 `iproxy` 进程持续运行。如果同时连接多台设备或使用了自定义端口，请为每台设备映射独立的本机端口，并在 Playground 或项目配置中填写对应端口。

### 确认 WDA 服务状态 {#verify-wda-status}

在运行 Midscene 的电脑上，通过浏览器或终端访问 WDA 的 `/status` 接口：

- **本机默认地址**：`http://localhost:8100/status`（若使用自定义端口、远程服务或网关，请访问实际的服务地址）
- **正常响应示例**：

```json
{
  "value": {
    "build": {
      "version": "10.1.1",
      "time": "Sep 24 2025 18:56:41",
      "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
    },
    "os": {
      "testmanagerdVersion": 65535,
      "name": "iOS",
      "sdkVersion": "26.0",
      "version": "26.0"
    },
    "device": "iphone",
    "ios": {
      "ip": "10.91.115.63"
    },
    "message": "WebDriverAgent is ready to accept commands",
    "state": "success",
    "ready": true
  },
  "sessionId": "BCAD9603-F714-447C-A9E6-07D58267966B"
}
```

返回的 JSON 中包含 `"ready": true` 即表示 WDA 服务已就绪。请记录该服务的主机地址与端口（或网关地址），以便后续在 Playground 和项目配置中使用。

## 验证 {#verify}

WDA 的 `/status` 返回 `"ready": true` 后，在 Playground 中验证环境。打开[开始使用](/zh/get-started.md?platform=ios\&scene=playground)，页面已为你选好 iOS 和 Playground，选择模型接入方式后，按步骤执行一次 `aiAct` 操作和一次 `aiAssert` 断言。断言通过即表示 WDA、屏幕截图、触控输入和模型调用都正常。

## 常见问题

### 为什么 WebDriverAgent 已连接，但仍无法控制真机设备？

请依次检查真机上的以下设置：

1. **开发者模式**：在系统「设置 > 隐私与安全性 > 开发者模式」中确认已开启并重启生效。
2. **UI Automation**：在系统「设置 > 开发者 > Enable UI Automation」中确认已开启。
3. **电脑信任授权**：重新插拔 USB 数据线，确保已在手机弹窗中点击「信任此电脑」。

### iOS 模拟器与真机在使用上有哪些区别？

| 特性               | iOS 真机            | iOS 模拟器       |
| ---------------- | ----------------- | ------------- |
| 端口转发             | 需要运行 `iproxy`     | 不需要（直接监听本机端口） |
| 开发者模式            | 需手动开启并重启手机        | 默认开启          |
| UI Automation 开关 | 需在「设置 > 开发者」中手动开启 | 默认开启          |
| 运行性能             | 真实硬件性能            | 取决于宿主机 Mac 性能 |
| 硬件传感器            | 真实传感器             | 模拟数据          |

### 如何自定义 WebDriverAgent 的端口和主机地址？

请参阅 [iOS JavaScript SDK](/zh/sdk/ios.md#如何自定义-webdriveragent-的端口和主机地址)。

### 如何在 Playground 中获得更流畅的实时投屏画面？

iOS Playground 的屏幕预览支持两种模式：

- **截图轮询模式**（默认）：逐帧调用 WDA 截图接口，帧率约为 5～10 fps。
- **原生 MJPEG 流模式**（推荐）：直接接入 WDA 内置的 MJPEG Server，帧率更高且延迟更低。

在真机上启用原生 MJPEG 流时，需额外将设备的 `9100` 端口（WDA MJPEG 默认端口）转发到 Mac 本机（模拟器无需转发）：

```bash
iproxy 9100 9100 YOUR_DEVICE_ID
```

Playground 启动时会自动探测本机 `9100` 端口：若端口可用，终端会输出 `MJPEG: streaming via native WDA MJPEG server` 并启用实时流；若不可用，则自动回退为截图轮询模式。