iOS真机Appium自动化启动失败：WebDriverAgentRunner签名及文件问题

我之前在做iOS真机Appium自动化测试时，完完全全碰到过和你一样的问题——启动测试就报错要卸载WDA，签名后还是没用，日志里一堆xcodebuild退出码65，说要选开发团队还找不到WebDriverAgentRunner-Runner.app。折腾了大半天终于搞定了，给你分享亲测有效的解决步骤：

核心问题拆解 #

这个报错本质是WebDriverAgent（WDA）的签名配置不完整，导致Xcode无法成功构建出WDA的运行包，进而Appium没法在真机上启动WDA服务。

具体解决步骤 #

1. 彻底配置WDA项目的签名（最关键） #

首先找到Appium自带的WDA项目路径：

• 一般默认路径是 /usr/local/lib/node_modules/appium/node_modules/appium-webdriveragent
• 如果你不确定，打开终端跑 appium doctor，日志里会显示WDA的位置

打开WebDriverAgent.xcodeproj，按以下步骤操作：

• 选中左侧的WebDriverAgentRunner target（一定要选Runner，不是Lib）
• 切换到Signing & Capabilities标签页：
  • 勾选Automatically manage signing
  • 在Team下拉菜单里选择你的开发团队（个人账号/公司开发者账号都可以，前提是这个账号已经把当前真机添加到设备列表里）
• 别忘了同步配置WebDriverAgentLib target的签名，同样选同一个开发团队，避免依赖库签名不一致
• 最后手动在Xcode里构建一次：选择你的真机设备，点击顶部的Build按钮，确保构建成功（Xcode左下角出现对勾）。这一步能直接解决“WebDriverAgentRunner-Runner.app不存在”的问题，因为构建成功后这个包就会生成在Xcode的DerivedData里。

2. 清理旧WDA残留并重启 #

• 打开iOS真机，删掉所有带WebDriverAgent字样的App（包括WebDriverAgentRunner、WebDriverAgentLib）
• 重启你的Mac和iOS真机，清除可能存在的缓存冲突

3. 配置Appium强制使用新的WDA实例 #

在你的测试代码的Desired Capabilities里添加：

# 以Python为例，其他语言类似
desired_caps = {
    # 你的其他配置...
    "useNewWda": True,
    "wdaLocalPort": 8100
}

或者启动Appium服务器时加参数：

appium --default-capabilities '{"useNewWda": true}'

这能避免Appium复用旧的、有问题的WDA进程。

4. 手动授权WDA（容易忽略的一步） #

当Xcode第一次在真机上安装WDA后，必须在iOS系统里授权：

• 打开iOS设置 → 通用 → VPN与设备管理
• 找到你的开发团队名称，点击进去选择“信任”
• 授权完成后，再重启一次WDA的运行，否则系统会阻止WDA启动

5. 验证Xcode命令行工具配置 #

确保你的Xcode命令行工具和Xcode版本匹配：

• 终端跑 xcode-select -p，输出应该是 /Applications/Xcode.app/Contents/Developer
• 如果路径不对，跑命令切换：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

额外排查点 #

• 如果是个人开发者账号：检查你的账号是否已经添加当前真机的UDID到开发者后台的设备列表里（没添加的话签名会失败）
• 如果是企业账号：确保你的账号有真机测试权限，且设备没有超出账号的设备数量限制
• 检查Xcode的版本：尽量使用稳定版，避免用Beta版Xcode，容易出现兼容性问题

内容的提问来源于stack exchange，提问作者Sidara KEO