iOS 真机环境准备
在 iOS 真机上运行 Munk AI 测试：配置已有 WDA，或通过源码脚本安装官方 WDA，并完成设备接入与验证。
要在 iOS 真机上跑 case，设备上需要有一份可用的 WebDriverAgent（WDA）。Munk AI 发行版（get.munk.sh）暂不提供 WDA 一键安装；你需要先完成一次性环境准备，之后日常只需 munk serve。
先选一条路径
| 你的情况 | 推荐路径 |
|---|---|
| 真机上已经装过 WDA（Appium、Xcode 等来源） | 使用已有 WDA |
| 还没有 WDA，或已有 WDA 经常出问题 | 安装 Munk 官方 WDA |
环境就绪后，两条路径都会汇合到 接入 Munk 并开始使用。
准备工作
开始之前，请确认：
- 你使用的是 Mac，且已安装 Xcode
- 已安装 Munk AI（
munk version可正常输出） - iPhone 通过 USB 连接 Mac（首次建议优先 USB，而不是纯 WiFi）
- 手机已解锁，并在手机上点了「信任此电脑」
- 系统版本为 iOS 17 及以上
- （仅官方安装路径）你有可用的 Apple Developer 签名能力
- （个人开发者账号）已在 Apple Developer → Devices 中录入这台测试设备的 UDID
获取设备 UDID
连接手机后，在终端执行：
xcrun devicectl list devices
记下目标设备对应的 UDID。后续安装 WDA 会用到它。
如果你使用的是个人开发者账号，还需要把该 UDID 登记到 Apple Developer 后台（Certificates, Identifiers & Profiles → Devices），并确保后续创建的 Provisioning Profile 已包含这台设备。未登记的设备无法用于 Development 签名安装。
你也可以在 Munk 启动后，用下面命令查看 device_ref（跑 case 时通常填这个值）：
munk devices list --platform ios
使用已有 WDA
如果你已经在真机上安装并跑通过 WebDriverAgentRunner，可以跳过编译安装，只在 Munk 里配置对应的 bundle id。
1. 确认 WDA 的 bundle id
常见示例（以你设备上实际安装的为准）：
com.facebook.WebDriverAgentRunner.xctrunner- 或你自己签名时配置的自定义 id
不确定时，可借助 Xcode Devices and Simulators，或你当初安装 WDA 时使用的 bundle id 记录。
2. 在 Apps 里填写 iOS WDA bundle id
- 启动服务：
munk serve --host 127.0.0.1 --port 16888 - 打开 Web UI：
http://127.0.0.1:16888/ - 进入 Apps → 创建或编辑你的 iOS App
- 填写 iOS bundle id（被测 App 的 bundle id）
- 在 iOS WDA bundle id 填入你设备上已安装 WDA 的 bundle id
- 保存
如果留空 iOS WDA bundle id，Munk 会默认使用 sh.munk.wda.xctrunner（适用于走下方官方安装流程的用户）。
3. 验证是否可用
在 Web UI 的 Devices 中，确认真机出现在设备列表，然后尝试跑一次 case。
若设备不可见、WDA 启动失败或 case 中途报错，请先核对 bundle id 是否填写正确。仍无法解决时，建议改用下方的 Munk 官方 WDA 安装流程。
说明： 其他来源的 WDA 未经 Munk 官方验证，兼容性无法保证。遇到稳定性问题时，推荐走官方安装流程。
安装 Munk 官方 WDA
当前发行版不包含 WDA 安装脚本。你需要从开源仓库获取脚本，在本地完成签名、编译和安装。
1. Clone 仓库
git clone https://github.com/chaxiu/munk-ai.git
cd munk-ai
相关脚本：
scripts/device/check_ios_wda_signing.py— 检查签名配置scripts/device/install_real_device_wda.py— 下载、编译并安装 WDA
Clone 仓库仅用于这一次环境准备；日常跑测试仍使用你已安装的
munk命令即可。
2. 创建签名配置文件
在本地创建 ~/.munk/ios_secrets.env（不要提交到 git）：
TEAM_ID=你的TeamID
IOS_WDA_BUNDLE_ID=sh.munk.wda
IOS_SIGNING_IDENTITY=Apple Development: 你的名字 (XXXXXXXXXX)
IOS_PROVISIONING_PROFILE_NAME=你的Profile名称
也可以用下面任一方式指定 Provisioning Profile（与 IOS_PROVISIONING_PROFILE_NAME 三选一）：
# IOS_PROVISIONING_PROFILE_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# IOS_PROVISIONING_PROFILE_PATH=~/Downloads/YourProfile.mobileprovision
如果构建时需要单独的 Runner profile，可额外添加：
# IOS_PROVISIONING_RUNNER_PROFILE_PATH=~/Downloads/YourRunnerProfile.mobileprovision
各字段获取方式：
| 字段 | 怎么填 |
|---|---|
TEAM_ID | 登录 Apple Developer → Membership → Team ID |
IOS_SIGNING_IDENTITY | 终端执行 security find-identity -v -p codesigning，复制完整 identity 字符串 |
IOS_PROVISIONING_PROFILE_NAME | 在 Apple Developer → Profiles 为 WDA 相关 bundle 创建 Development profile，下载后双击安装到 Mac，再填 profile 名称 |
IOS_WDA_BUNDLE_ID 建议保持 sh.munk.wda。安装成功后，Apps 里的 iOS WDA bundle id 可留空，Munk 会使用默认值 sh.munk.wda.xctrunner。
3. 检查签名是否就绪
在仓库根目录执行：
python3 scripts/device/check_ios_wda_signing.py \
--signing-env-file ~/.munk/ios_secrets.env
输出中 "ok": true 表示可以继续。若为 false，按终端里的报错修正 ios_secrets.env 后重试。
4. 安装 WDA 到真机
将 <UDID> 替换为你在 准备工作 中获取的设备 UDID：
python3 scripts/device/install_real_device_wda.py \
--device-udid <UDID> \
--signing-env-file ~/.munk/ios_secrets.env
安装过程会自动完成下载源码、编译、安装到手机、启动 WDA 和健康检查。成功时，终端 JSON 输出中会出现：
"ok": true,
"stage": "completed"
常用可选参数：
--force-rebuild— 强制重新编译--force-download— 强制重新下载 WDA 源码
以下情况建议重新安装：更换手机、证书轮换、iOS 大版本升级、或 WDA 持续无法启动。
接入 Munk 并开始使用
1. 启动服务
munk serve --host 127.0.0.1 --port 16888
2. 确认设备可见
浏览器打开 http://127.0.0.1:16888/，在 Devices 查看设备列表。
也可以用 Local API 确认：
http://127.0.0.1:16888/v1/devices?platform=ios
或用 CLI：
munk devices list --platform ios
3. 配置 iOS App
Web UI → Apps → 创建或编辑 App：
| 字段 | 说明 |
|---|---|
| 平台 | 选择 ios |
| iOS bundle id | 被测 App 的 bundle id |
| iOS WDA bundle id | 使用已有 WDA 时填写；官方安装完成后可留空 |
4. （可选）Settings 中的 iOS Bridge
大多数 USB 连接 的用户可以跳过这一步。
如果你使用 WiFi 连接 且系统为 iOS 18+，可能需要在 Web UI → Settings 中：
- 开启 用 sudo 启动 ios-device-bridge
- 填写本机 sudo 密码
5. 跑第一条 case
Web UI
- 进入 Runs（或从 Dashboard 发起执行）
- 选择你的 iOS App 和已连接的真机
- 执行 case
CLI 快速验证
将 <device-ref> 替换为 munk devices list --platform ios 输出中的 device_ref：
munk run case \
--app-id <your-app-id> \
--plan-id <plan-id> \
--case-id <case-id> \
--platform ios \
--device-ref <device-ref> \
--bundle-id <被测App的bundle-id> \
--config ./munk.yaml
对于 run plan、verify change 等可复现工作流，建议在 Apps 中维护好 iOS profile，再通过 JSON 请求文件或 Web UI 发起执行。
验证是否成功
完成配置后，建议逐项确认：
-
munk doctor无阻塞性错误 - 真机出现在 Web UI 设备列表或
munk devices list --platform ios输出中 - 成功跑完一次 case
- Run 详情中没有持续的 WDA 启动 / session 失败报错
常见问题
| 现象 | 处理步骤 |
|---|---|
| 设备列表为空 | 检查 USB 连接；解锁手机；重新点「信任此电脑」；拔插数据线后重试 |
signing_check_failed | 按 检查签名 修正 ios_secrets.env；确认证书未过期 |
| WDA 启动失败（已有 WDA） | 核对 Apps 中 iOS WDA bundle id 是否与设备上实际安装一致 |
| WDA 启动失败（官方安装） | 重新执行 安装命令；必要时加 --force-rebuild |
| 第三方 WDA 交互异常 | 改用 Munk 官方 WDA 安装流程 |
| case 报错与锁屏相关 | 保持手机亮屏、解锁状态后再跑 |
| WiFi 真机（iOS 18+）连不上 | 在 Settings 开启 sudo bridge；参考 Appium Remote XPC Tunnels |
| 换手机或换证书后失败 | 对新设备重新执行官方安装流程 |
下一步读什么
- 快速开始 — 安装 Munk、
munk serve与 Web UI 入门 - 执行工作流 —
run case、run plan与verify change - munk-ai 仓库 — 获取 WDA 安装脚本