Appium运行报xcodebuild错误无法启动WebDriverAgent如何解决

• 你当前使用的Appium 1.17内置的WebDriverAgent（WDA）版本过旧，与Xcode 12.5.1、Carthage 0.38.0的兼容性存在已知缺陷，旧版WDA的Carthage依赖配置没有适配高版本Carthage的xcframework要求，也不支持Xcode 12.5的编译规则。
• 你编写的Capabilities配置缺少必要的自动化引擎参数，也是触发启动失败的原因之一。

步骤1：替换适配版本的WDA #

优先推荐升级Appium到2.x正式版，新版已内置适配高版本Xcode的WDA，无需手动替换。
若需保留现有Appium 1.17版本，可单独下载适配Xcode 12.5的WebDriverAgent安装包，替换Appium安装目录下的node_modules/appium-xcuitest-driver/WebDriverAgent路径下的所有文件。

步骤2：重新编译WDA依赖 #

进入替换后的WDA目录，依次执行以下命令：

# 编译Carthage依赖，适配当前Carthage版本要求
carthage bootstrap --use-xcframeworks --platform iOS,tvOS --no-use-binaries
# 执行WDA官方初始化脚本
./Scripts/bootstrap.sh -d

步骤3：Xcode重新配置WDA签名 #

• 用Xcode打开WebDriverAgent.xcodeproj
• 分别为WebDriverAgentLib、WebDriverAgentRunner两个target配置你的开发者签名，确保bundle id无冲突
• 选择你的测试模拟器/真机，运行WebDriverAgentRunner target，确认编译成功且设备上能正常启动WDA服务

步骤4：修正Capabilities配置 #

补充必要的启动参数，修改后的配置如下：

DesiredCapabilities cap = new DesiredCapabilities();
cap.setCapability("platformName", "iOS");
cap.setCapability("platformVersion", "14.5");
cap.setCapability("deviceName", "iPhone 12");
cap.setCapability(CapabilityType.BROWSER_NAME, "safari");
// 补充必要参数
cap.setCapability("automationName", "XCUITest"); // 必须指定iOS自动化引擎
cap.setCapability("useNewWDA", true); // 每次启动自动卸载旧版WDA避免冲突
cap.setCapability("wdaLaunchTimeout", 120000); // 延长WDA启动超时时间
cap.setCapability("waitForAppScript", "true");

URL url = new URL("http://127.0.0.1:4723/wd/hub");
IOSDriver driver = new IOSDriver(url, cap);

备选降级方案 #

如果不想替换WDA和升级Appium，可将Carthage降级到0.37.0版本，旧版Carthage不需要--use-xcframeworks参数，兼容Appium1.17自带的WDA配置：

brew uninstall carthage
brew install carthage@0.37.0

降级完成后重新执行原教程中的./Scripts/bootstrap.sh -d即可。

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