iOS 免越狱自动化实战：WebDriverAgent 安装与版本踩坑全记录
本文基于 control_mobile 项目的真实部署经验整理。我们在做 iOS 免越狱群控（多 App 自动注册、截图识别、批量操作）时，踩遍了 WDA 安装与版本兼容的坑。如果你也在搞 iPhone 自动化，这篇应该能帮你少绕几圈。
一、为什么非 WDA 不可？
苹果把点击、输入、截图、读控件树这些能力全部锁在私有 API 里，没有任何公开接口能让外部程序直接操控其他 App。
WebDriverAgent（简称 WDA）的巧妙之处在于：它把自己做成一个永不结束的 XCUITest 测试，在手机上跑一个 HTTP 服务（默认 8100 端口），把 XCUITest 能力暴露成 REST 接口。Appium 的 XCUITest Driver 也是基于它。
在 control_mobile 项目里，整条调用链是这样的：
Python 脚本 (facebook-wda)
↓ HTTP
手机上的 WDA (:8100)
↓ XCTest
操作目标 App（Tinder、Meetic 等）
没有 WDA，点击、输入、截图全部无法工作。 它是整个 iOS 自动化链路的底座，不是可选组件。
二、一次性准备：编译签名 WDA
WDA 不是 pip install 能搞定的，必须走 Xcode 编译签名装到真机上。核心步骤：
- 从 appium/WebDriverAgent 下载源码（ZIP 或 git clone）
- Xcode 打开
WebDriverAgent.xcodeproj - 选
WebDriverAgentRunnertarget → Signing & Capabilities → 用你的 Apple ID 自动签名 - Bundle Identifier 改成唯一值（如
com.yourname.WebDriverAgentRunner，com.facebook.*会注册失败） - 真机 + Product → Test（Cmd+U） 编译安装
- 手机出现 "Automation Running" 悬浮条 = 成功
- 把
<RunnerBundleId>.xctrunner填进项目config.json
⚠️ 常见误区：点运行按钮 ▶ 会报 "Could not launch IntegrationApp"。WDA 必须用 Cmd+U（Test），不是 Run。
装好后，日常由 go-ios 的 ios runwda 启动，不必每次开 Xcode。
三、版本踩坑：Mac / Xcode / iOS 三环相扣
这是最近换手机、换 Mac 时踩得最狠的坑。三者必须匹配，一环不对就全盘失败。
3.1 对照表
| 手机 iOS | 最低 Xcode | Xcode 需要的 macOS | 典型报错 |
|---|---|---|---|
| ≤ 16.4 | Xcode 15.2 | Ventura 13.5+ | — |
| 17.x | Xcode 15.x | Ventura / Sonoma | 需起隧道 |
| 18.x | Xcode 16.x | Sonoma 14.5+ | Failed to prepare the device |
Xcode 自带的「设备支持文件」有上限。手机 iOS 越新，需要的 Xcode 越新；而 Xcode 版本又受 macOS 限制；macOS 又受 Mac 机型限制。
真实案例：2017 款 Intel Mac 最高只能装 Ventura → 最高 Xcode 15.2 → 设备支持只到 iOS 16.4。拿它给 iOS 18 手机装 WDA，必然卡在 Failed to prepare the device for development。签名装 App 的活，得交给能跑 Xcode 16 的 Mac。
3.2 下载指定版本 Xcode
推荐用 xcodereleases.com 查全版本列表，跳到 Apple 官方下载 .xip：
cd ~/Downloads && xip --expand Xcode_16.x.xip
sudo mv /Applications/Xcode.app /Applications/Xcode-old.app # 保留旧版
mv ~/Downloads/Xcode.app /Applications/Xcode.app
sudo xcode-select -s /Applications/Xcode.app
xcodebuild -version # 确认版本
3.3 xcodegen 工程格式不兼容
如果项目用 xcodegen 生成辅助 App（如推图入相册的 PhotoImporter），xcodegen 2.45.x 默认生成 Xcode 16 格式（objectVersion = 77），Xcode 15.x 打开会报 future Xcode project file format，点设置面板直接崩溃。
一行 sed 降回 Xcode 15 能认的格式：
sed -i '' 's/objectVersion = 77;/objectVersion = 56;/; /preferredProjectObjectVersion = 77;/d; /minimizedProjectReferenceProxies = 1;/d' PhotoImporter.xcodeproj/project.pbxproj
每次重新
xcodegen generate都会变回 77，记得重跑。
四、iOS 17+ 的隧道：新门槛
苹果从 iOS 17 起把开发者服务改到 RemoteXPC，必须先建隧道才能启动 WDA：
# Mac
sudo ios tunnel start # 保持终端一直开着
# Windows（需管理员 + wintun.dll）
ios tunnel start
control_mobile 的 wda_launcher.py 会自动读取设备 iOS 版本，iOS 17+ 自动尝试起隧道，iOS ≤16 跳过：
def _needs_tunnel(ios_version: str) -> bool:
major = int(ios_version.split(".")[0])
return major >= 17
Windows 上注意：config.json 里 tunnel.use_sudo 必须改成 false（Windows 没有 sudo），靠「以管理员身份运行终端」起隧道。还需从 wintun.net 下载 wintun.dll 放到 System32 或 ios.exe 同目录。
五、签名有效期：7 天 vs 1 年
| 账号类型 | WDA 可用时长 | 到期现象 |
|---|---|---|
| 免费 Apple ID（Personal Team） | 7 天 | WDA 启动超时、runwda 无响应 |
| 付费开发者账号（$99/年） | 1 年 | 群控多台强烈推荐 |
免费账号到期后，回 Xcode 对已连接设备重新 Cmd+U 即可刷新。群控大量设备时，要么上付费账号，要么写批量重签脚本定期处理。
另一个签名坑：免费个人账号的 Team ID 会变，钥匙串旧证书失效，报 No Account for Team "XXXXXXXXXX"。最省事的做法是跟已经装成功的 WDA 用同一个 Team，或直接把 DEVELOPMENT_TEAM 写进 project.pbxproj，绕开 Xcode 设置面板崩溃。
命令行
xcodebuild签不了免费账号——命令行进程读不到 Xcode GUI 里登录的 Apple ID。免费账号只能用 Xcode 图形界面 Cmd+U 签名安装。
六、日常启动：go-ios 三板斧
WDA 装好后，control_mobile 用 go-ios 三板斧拉起：
ios runwda --bundleid=com.xxx.WebDriverAgentRunner.xctrunner \
--testrunnerbundleid=com.xxx.WebDriverAgentRunner.xctrunner \
--xctestconfig=WebDriverAgentRunner.xctest
ios forward 8100 8100 --udid=<UDID> # 端口转发到本机
# 轮询 http://localhost:8100/status 直到 200
多台设备时，每台分配独立本机端口（local_port_start 递增），iOS 17+ 多台共用一个隧道守护。
Python 侧用 facebook-wda 连 http://localhost:<port> 发点击、输入、截图指令。
七、Windows 也能跑（但编译仍需 Mac）
WDA 在 Mac 上编译签名装到手机后，日常自动化可以在 Windows 上跑（go-ios、facebook-wda、pymobiledevice3 都跨平台）。
Windows 额外注意：
- go-ios：直接下 go-ios-win.zip，不用装 Node
- iTunes：必须装官网版（非微软商店版），否则 USB 认不到设备
- pymobiledevice3：依赖
lzfseC 扩展，Windows 无预编译 wheel，需装 Microsoft C++ 生成工具 才能 pip install - 签名到期重签：仍需回 Mac 用 Xcode，Windows 只能「用」不能「造」
八、常见问题速查
| 现象 | 原因 | 解法 |
|---|---|---|
Failed to prepare the device |
Xcode 版本 < 手机 iOS | 升 Xcode 或换能跑 Xcode 16 的 Mac |
| WDA 启动超时 | 签名过期 / 未信任证书 / 隧道未起 | 重签 Cmd+U、信任证书、起隧道 |
Failed to register bundle identifier |
Bundle ID 冲突 | 改成唯一值 |
| 换了新手机没反应 | 新设备未装 WDA | 对新设备单独 Cmd+U，config 加 UDID |
| 升级手机系统后失效 | 需更高 Xcode / 重挂调试镜像 | 升 Xcode + 重装 WDA |
工程future Xcode project file format |
xcodegen 生成 Xcode 16 格式 | sed 降 objectVersion 到 56 |
No Account for Team |
Team ID 失效 / 命令行签免费号 | 用 WDA 同一 Team，GUI 签名 |
九、一句话总结
WDA 是 iOS 免越狱自动化的唯一公开可行底座。装一次能用很久，但要注意：
- Mac / Xcode / iOS 三者版本必须匹配
- iOS 17+ 必须起隧道
- 免费签名 7 天到期要重签
- 编译签名在 Mac，日常跑脚本可以 Windows
在 control_mobile 项目里，我们把版本判断、隧道拉起、端口转发、健康检查都封装进了 wda_launcher.py，上层只管调 facebook-wda 发指令。底座踩过的坑，希望这篇能帮你少踩一遍。
相关资源
- WDA 源码：https://github.com/appium/WebDriverAgent
- go-ios：https://github.com/danielpaulus/go-ios
- Xcode 全版本：https://xcodereleases.com
- wintun（Windows 隧道）：https://www.wintun.net/