Appium Inspector创建iOS测试会话失败，请求排查解决

环境配置 #

• Macbook air m1
• npm安装的Appium v1.22.3
• Appium Desktop v1.22.3-4
• 手动替换了WebDriverAgent v4.9.0
• Appium Inspector来自官方发布版本

无论命令行还是GUI启动Appium服务器，均出现相同错误，无法运行iOS自动化测试。

会话配置参数 #

{
  "appium:deviceName": "iPhone SE",
  "platformName": "iOS",
  "appium:platformVersion": "16.1",
  "appium:automationName": "XCUITest",
  "appium:udid": "00008030-001939C20207802E",
  "appium:app": "/app.ipa",
  "appium:bundleId": "com.iphone.Skull-iQ.dev",
  "appium:xcodeSigningId": "iPhone Developer",
  "appium:xcodeOrgId": "XXXX"
}

核心错误日志 #

[debug] [Appium] /opt/homebrew/lib/node_modules/appium/node_modules/appium-webdriveragent/index.js:1
[debug] [Appium] import * as dependencies from './lib/check-dependencies';
[debug] [Appium] ^^^^^^
[debug] [Appium] 
[debug] [Appium] SyntaxError: Cannot use import statement outside a module
...
(node:945) [DEP0128] DeprecationWarning: Invalid 'main' field in '/opt/homebrew/lib/node_modules/appium/node_modules/appium-webdriveragent/package.json' of './build/index.js'. Please either fix that or report it to the module author
...
[debug] [W3C] Encountered internal error running command: Error: Could not load a driver for automationName 'XCUITest' and platformName 'iOS'. Please verify your Appium installation

问题原因 #

手动替换的WebDriverAgent v4.9.0采用了ES模块语法（import语句），但Appium v1.22.3依赖的appium-xcuitest-driver仍使用CommonJS模块规范加载依赖，两者不兼容。同时WDA的package.json中main字段指向的文件路径无效，进一步导致加载失败。

解决步骤 #

1. 恢复Appium内置的兼容版WebDriverAgent #

手动替换的WDA版本与当前Appium版本不匹配，需移除手动替换的文件，让Appium重新安装适配版本：

# 定位到Appium的appium-webdriveragent目录
cd /opt/homebrew/lib/node_modules/appium/node_modules/appium-webdriveragent
# 删除当前手动替换的内容
rm -rf ./*
# 重新安装该模块的适配版本
npm install

2. 验证Appium与WebDriverAgent版本兼容性 #

Appium版本与WDA版本存在严格的对应关系，不要随意手动替换。如果需要特定版本的WDA，应通过安装对应版本的appium-xcuitest-driver来间接获取：

# 卸载当前的xcuitest驱动
npm uninstall -g appium-xcuitest-driver
# 安装与Appium v1.22.3兼容的版本（可查看Appium官方文档确认对应版本）
npm install -g appium-xcuitest-driver@4.20.0

3. 检查Node.js版本兼容性 #

Appium v1.22.3建议使用Node.js 14.x或16.x版本，过高的Node.js版本可能导致模块加载问题。可通过nvm切换版本：

# 如果未安装nvm，可通过官方方式安装
# 切换到Node.js 16.x
nvm install 16
nvm use 16

4. 重新启动Appium服务 #

完成上述操作后，重启Appium服务器，再次尝试创建测试会话。

内容的提问来源于stack exchange，提问作者u_u-de