iOS自动化测试环境搭建全攻略：从Appium到WebDriverAgent部署避坑指南

1. 为什么iOS自动化测试总是卡在环境配置

我接触iOS自动化测试的第一天，就被环境配置上了一课。当时接手一个跨平台App的测试任务，Android侧跑得顺风顺水，到了iOS侧，光是让Appium连上真机就折腾了整整两天。后来回头看，90%的时间都耗在了WebDriverAgent的编译和部署上。

先说清楚这套体系的组成。Appium本身是一个跨平台的自动化测试框架，它通过协议与各个平台的驱动层通信。在iOS上，这个驱动层就是WebDriverAgent（简称WDA）。WDA是打通Appium与iOS设备之间的桥梁——Appium下发指令，WDA负责把指令转换成苹果的测试框架能识别的操作，再通过测试框架驱动App。你可以把WDA理解成一个翻译官，把Appium说的“通用语言”翻译成iOS设备能执行的“本地语言”。

为什么要专门写一篇文章说配置流程？因为iOS自动化测试的痛点从来不在测试代码本身，而在环境搭建。Xcode版本不匹配、证书签名问题、端口占用、依赖库缺失，任何一个环节出错，都会让整个测试环境瘫痪。而这些问题恰恰是官方文档里写得最简略的部分。我见过太多人卡在安装依赖之后的第一步——WDA编译不过去，然后整个项目就搁浅了。

这篇文章写给谁看？三类人：一是刚接触iOS自动化测试，想快速跑通一套环境的测试开发工程师；二是已经在用Appium但被各种环境问题反复折磨的同行；三是需要维护CI/CD环境，希望拿到一份可复用的避坑清单的运维或基建同学。内容覆盖从环境准备到WDA编译部署，再到常见错误的完整解法，尽量把我在实际项目中踩过的坑、填过的土都交代清楚。

2. 整套环境的技术选型与版本匹配思路

2.1 为什么要选Appium + WebDriverAgent这套组合

市面上做iOS自动化测试的方案不止一种。XCTest框架本身自带UI测试能力，可以做端到端的自动化验证，但它有个硬伤——用例必须写在Xcode工程里，通过Xcode编译运行，对非原生开发团队的测试同学来说门槛偏高。另一个选择是XCUITest直接驱动，加上一些第三方封装，但项目一旦涉及跨平台（Android + iOS双端跑同一套用例），这些方案就暴露出各自的短板。

Appium + WDA的优势在于统一。Appium的WebDriver协议屏蔽了Android和iOS的差异，测试用例可以用同一套逻辑写，只是通过capabilities切换平台。WDA在这一体系里扮演了执行层的角色，负责接收Appium的指令并驱动iOS上的XCTest框架完成实际的操作。所以这套组合的完整链路是：测试用例 → Appium Server → WDA → XCTest框架 → 被测App。

这套方案在社区活跃度、文档丰富度、问题排查资源方面都有明显优势。遇到问题搜索一下，基本都能找到前人踩坑的记录，这对于环境类问题的排查来说极其重要。

2.2 版本匹配是环境搭建的第一优先级（血泪教训）

先讲一个我踩过的最大的坑：版本随意搭配，结果浪费了一整周。

当时我用的Xcode版本偏新，但Appium版本比较旧，两者组合之下，WDA编译通过后却始终无法正常启动，报错信息指向一个非常隐蔽的底层协议兼容问题。后来查证才发现，新版本Xcode对测试框架的启动方式和通信协议做了调整，旧版WDA对应的代码还在用旧的调用方式，两边自然对不上。

所以配置环境之前，第一步必须是确定版本组合。以我目前用得比较多、实测比较稳的组合为例：

需要说明的是，上面的版本对应关系是参考性的，实际操作时以官方文档的更新为准。核心原则是：Appium升级时，同步确认WDA是否需要更新，Xcode升级时，确认当前WDA版本是否兼容新的SDK。

2.3 硬件与系统环境的预先检查

版本之外，硬件和系统层面也有一些硬性条件需要提前确认，否则编译到一半才发现问题，返工成本很高。

• 必须使用macOS系统，因为iOS应用的编译和签名只能在macOS上完成。Windows或Linux环境下，即使能通过网络连接到Mac执行测试，WDA的源码编译这一步还是必须在Mac上操作。
• 磁盘空间建议预留至少30GB。Xcode本身占用很大空间，加上依赖库和构建缓存，空间不足会导致编译过程中出现莫名其妙的文件写入失败。
• 真机调试需要数据线直连，建议使用原装线或MFi认证的线缆。劣质数据线在长时间测试过程中容易出现连接闪断，导致测试中断。
• 确保Mac和iOS设备连接的是同一局域网，同时Mac的防火墙不要拦截相关端口通信，否则后续WDA与Appium之间的通信会出问题。

3. 环境准备与依赖安装全流程

3.1 基础依赖清单

开始配置之前，先把基础环境弄干净。下面是需要的依赖项及其用途说明：

每个依赖都有其特定作用。Homebrew是macOS上的包管理器，用于安装其他工具；Node.js是Appium的运行环境；Appium本身是测试框架的服务端；Carthage是WDA编译时用来拉取和构建第三方库的工具。这里的顺序也很重要，因为后面的工具依赖前面的安装。

3.2 安装步骤与常见执行结果

第一步：安装Homebrew

# 检查是否已安装 brew --version # 未安装时执行 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，建议执行brew doctor检查环境是否存在告警。常见的告警是目录权限问题，按提示修复即可，不处理可能会影响后续的工具安装。

第二步：安装Node.js

brew install node node -v npm -v

如果Mac上已经安装了其他版本的Node.js，建议通过版本管理工具如nvm统一管理，避免全局环境混乱。Node版本过低可能导致Appium运行时报错，如果遇到这种情况，升级Node版本通常可以解决。

第三步：安装Appium

npm install -g appium appium --version

Appium的全局安装路径需要注意权限问题。如果执行npm install -g时遇到权限不足的报错，可以按照npm的错误提示，修正当前用户对全局目录的写入权限后重新执行。

第四步：安装Carthage

brew install carthage carthage version

这一步和WDA编译直接相关。WDA的工程文件中使用Carthage管理依赖，编译时依赖缺失会直接导致失败。具体的依赖内容在WDA源码目录下的Cartfile文件中定义，最常见的是路由相关的库。

3.3 关于Appium版本固化的建议

很多人在搭建环境时习惯直接安装最新版本，我一开始也是，直到被坑过一次才改掉这个习惯。最新版本虽然功能最新，但往往存在与现有WDA或Xcode版本不匹配的风险。除非你是为了体验新功能，否则建议安装一个已经验证过的稳定版本，比如：

npm install -g appium@2.x.x # 或指定一个你验证过的版本号

项目稳定运行时的环境组合建议记录下来形成文档，团队新同学搭建环境时照着文档操作即可，能省去大量摸索成本。我参与过的每个自动化测试项目，都会在README中单独开一节写环境版本矩阵，这种做法在实际协作中带来了非常直接的效率提升。

4. WDA编译部署的核心流程

4.1 获取WDA源码

WDA的源码托管在GitHub上，获取方式很直接：

git clone https://github.com/appium/WebDriverAgent.git cd WebDriverAgent

这里要注意，源码需要和当前Appium版本匹配。如果你的Appium版本较老，对应的WDA版本也应该选择兼容的分支或标签，而不是直接拉取最新的主干代码。新版本WDA需要的新Xcode特性在旧环境中可能不可用，反之旧版本WDA在Xcode升级后也可能编译失败。

4.2 关键的一步：重命名项目

这一步是大部分教程没有专门强调、但实际工作中极其重要的操作。WDA源码中的工程文件名为WebDriverAgent.xcodeproj，编译出的Runner应用会带上这个默认名称。当同一台Mac连接多台iOS设备时，如果所有设备的WDA都叫这个名字，设备管理就会出现冲突。

我的做法是给每个设备创建独立命名的WDA副本，比如：

WebDriverAgent_iPhone12 WebDriverAgent_iPhone15

目录名可以任意，只要能区分。实际操作时直接复制整个源码目录后，用任意编辑器打开Info.plist文件，修改CFBundleDisplayName和CFBundleName字段的值，用设备名称命名即可。这样每台设备上安装的Runner应用都有独立名字，互不干扰。

4.3 签名配置的完整步骤

签名是WDA配置中出问题最多的一个环节。先明确一个背景：WDA本质上是一个供测试阶段使用的应用，它必须经过签名才能被安装并运行在iOS设备上。使用个人开发者账号（Apple ID免费签名）时，必须开启开发者模式。如果使用付费开发者账号，需要在开发者后台将设备的UDID注册到账号中。

4.3.1 在Xcode中配置签名

1. 双击打开WebDriverAgent.xcodeproj工程文件。
2. 在项目导航栏中，选中WebDriverAgentRunnertarget。
3. 进入Signing & Capabilities面板。
4. 在Team下拉框中，选择你的开发者账号。
5. 确认Bundle Identifier没有被其他应用占用。如果默认的ID已被占用，手动修改成唯一值，比如com.yourname.wda.runner。
6. 选中Automatically manage signing，让Xcode自动生成对应的描述文件。

下图是配置完成后应呈现的状态说明：Team显示你的账号名，Signing Certificate显示对应的证书信息，Provisioning Profile显示自动生成的描述文件。这几项为空或显示红色警告，说明签名尚未配置成功。

4.3.2 真机开发者模式的开启

iOS 16及以上系统，设置中新增了开发者模式开关。真机执行自动化测试前必须手动开启：设置 → 隐私与安全性 → 开发者模式 → 打开。开启后设备会提示重启，重启后还需要在弹窗中确认一次。没有完成这一步的话，WDA安装到设备上后无法启动，或者启动后立即闪退。

4.3.3 签名配置错误的影响

签名配置错误，测试用例能正常编译通过，但安装到真机后运行会直接闪退，且日志中报错信息不明确。整个排查过程中，我养成了一个习惯：只要遇到XCTestRunner闪退，先检查签名和开发者模式，再考虑其他原因。

4.4 前置编译命令与依赖加载

签名配置完成后，先执行WDA依赖的加载和编译验证：

cd WebDriverAgent carthage bootstrap --platform iOS --use-xcframeworks

--use-xcframeworks参数让Carthage以xcframework的形式集成依赖，这种格式在Xcode 12及以上版本中兼容性更好。执行过程会联网下载依赖库，耗时取决于网络状况。执行完成后，确认Carthage/Build/iOS目录下生成了对应的framework文件，这一步是后续编译成功的前提。

4.5 执行编译命令

编译命令是环境搭建中最关键的一步。使用xcodebuild，最终的目标产物是WebDriverAgentRunner-Runner.app。

xcodebuild -project WebDriverAgent.xcodeproj \ -scheme WebDriverAgentRunner \ -configuration Debug \ -destination 'platform=iOS,id=<设备的UDID>' \ -derivedDataPath ./DerivedData \ CODE_SIGNING_ALLOWED=YES \ build

重点说明几个参数的含义：

• -project：指定工程文件路径。
• -scheme：指定使用的构建配置，必须选WebDriverAgentRunner。
• -destination：指定目标设备，需要换成你当前连接的真机UDID。
• -derivedDataPath：指定编译产物的输出目录。给这个参数显式指定路径，可以避免Xcode默认的随机路径，方便后续直接引用编译产物。
• CODE_SIGNING_ALLOWED=YES：显式允许代码签名。不加这个参数时，某些自动化场景下会因签名问题导致编译失败。

4.6 编译产物说明

编译成功后，产物位于./DerivedData/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app。这个路径在后续启动WDA时需要用到。编译过程可能耗时数分钟，取决于机器性能。第一次编译需要连接开发者服务做签名，耗时会更明显，后续编译会有缓存，速度会快很多。

5. xcodebuild编译失败错误全解析

这一部分，我整理了实际项目中遇到频率最高、最典型的编译错误，并给出排查思路和解决方案。

5.1 签名相关的错误

错误一：Signing for "WebDriverAgentRunner" requires a development team

完整报错信息大致为：

Signing for "WebDriverAgentRunner" requires a development team. Select a development team in the Signing & Capabilities editor.

这个错误的意思是，当前工程没有配置开发者团队，无法完成签名。解决方案：打开Xcode工程，在Signing & Capabilities面板中，为WebDriverAgentRunner的target选择你的Team。如果你用的是免费Apple ID，第一次添加时Xcode会提示你启用该账号的开发功能，按提示操作即可。

错误二：No profiles for '...' were found

完整报错信息为：

No profiles for 'com.xxx.xxx' were found. Xcode couldn't find any iOS App Development provisioning profiles matching 'com.xxx.xxx'.

意思是找不到匹配的描述文件。常见原因是Bundle Identifier与账号下已有的描述文件不匹配。解决思路：修改Bundle Identifier，换成当前账号下没有使用过的唯一ID，回到Xcode重新生成描述文件。如果设备UDID没有注册到账号内，也需要先在开发者后台添加设备并重新生成描述文件。

错误三：Provisioning profile "..." doesn't include signing certificate

完整报错信息为：

Provisioning profile "iOS Team Provisioning Profile: *" doesn't include signing certificate "Apple Development: ...".

描述文件与证书不匹配。解决思路：删除旧的描述文件和证书，在Xcode的Preferences → Accounts中移除并重新添加Apple ID，然后重新执行签名配置。这种做法能强制Xcode重新生成匹配的证书与描述文件组合，解决大部分签名不匹配的顽固问题。

5.2 Carthage依赖相关的错误

错误四：carthage: command not found

输入carthage命令时提示找不到命令。原因很简单：Carthage没有安装。按上文步骤执行brew install carthage即可。如果已经安装但系统提示找不到，检查一下PATH环境变量是否包含了$(brew --prefix)/bin路径。

错误五：No Carthage dependency found或Check dependencies failed

完整报错信息为：

Check dependencies failed: No Carthage dependency found. Please run 'carthage bootstrap' before building.

说明WDA依赖库还没有被构建出来。解决方案是执行：

carthage bootstrap --platform iOS --use-xcframeworks

这个过程需要网络下载源码并编译，如果网络被限速或仓库地址访问异常，会耗时很久或直接失败。如果公司网络策略限制了对GitHub的访问，可以尝试切换网络或配置临时代理后重试。

5.3 设备连接相关的错误

错误六：Unable to find a device matching the specified destination

完整报错信息为：

Unable to find a device matching the specified destination.

xcodebuild没有找到匹配的设备。可能原因：设备未正确连接到Mac、设备未处于解锁状态、设备没有信任这台Mac、UDID输入错误。排查顺序：先检查Xcode的Devices面板能否看到该设备；再检查设备的信任弹窗是否已点击确认；最后确认UDID是否复制正确。

错误七：The developer disk image could not be mounted

完整报错信息为：

The developer disk image could not be mounted on the device.

这是一个比较隐蔽的问题，通常出现在iOS系统版本过新而Xcode版本过旧的时候。设备系统要求Xcode包含对应版本的开发者镜像，Xcode版本不足以支持当前的系统版本时就会出现这个错误。解决办法是升级Xcode到支持对应系统版本的版本。

5.4 编译中期的错误

错误八：Lexical or Preprocessor Issue或Module not found

报错信息示例：

error: module map file '/path/to/xxx.modulemap' not found

这类问题的共性指向是依赖库缺失或路径不匹配。优先排查Carthage依赖是否已完整构建，确认Carthage/Build目录下的framework文件都存在。如果存在但仍然报错，尝试清理缓存后重新构建：

rm -rf ~/Library/Caches/org.carthage.simulation rm -rf Carthage carthage bootstrap --platform iOS --use-xcframeworks

清理脚本的执行时机放在Carthage重新构建之前，这样不会因为旧的缓存文件干扰新的构建过程。这个方法解决了我遇到过的绝大多数依赖相关编译错误。

5.5 我非常想单独分享的错误：重复签名错误

错误九：errSecInternalComponent

完整报错信息为：

error: Failed to create provisioning profile. The app ID "com.xxx.xxx" cannot be registered to your development team. Change your bundle identifier to a unique string to try again.

或者：

Checking signing state failed with error: errSecInternalComponent

这种情况通常不太常见，但一旦出现非常折磨人。errSecInternalComponent表示访问钥匙串时出现了权限问题。解决步骤参考：

1. 打开钥匙串访问应用。
2. 在左侧菜单中选择登录，点击解锁。
3. 找到与开发者证书相关的私钥，右键选择获取信息，在访问控制选项卡中勾选允许所有应用程序访问此项目。
4. 重启Xcode，重新编译。

执行以上操作前，最好先确认当前Mac用户对钥匙串目录有正常的读写权限，权限异常时调整权限后再继续解锁流程会更快见效。这个方法要慎用，因为它降低了钥匙串的安全性，但在本机开发和测试环境下，这是解决此类错误最直接有效的方式。

6. 启动WDA：把编译产物部署到真机

6.1 安装Runner到真机

编译产物正确部署到设备有几种方式。我常用的方法是：

xcrun simctl install booted <app路径> # 模拟器环境

真机环境的安装命令：

ios-deploy --id <UDID> --bundle <app路径>

ios-deploy是一个命令行工具，可以通过brew install ios-deploy安装，专门用于向真机安装和调试应用。如果觉得命令行步骤太繁琐，也可以直接用Xcode运行WebDriverAgentRunner这个scheme，把应用跑起来，操作起来更直观，适合第一次部署时观察应用在设备上的运行状态。

6.2 启动WDA服务并验证连通性

WDA在设备上启动后，会开启一个HTTP服务。我使用的启动命令是：

xcodebuild test-without-building \ -project WebDriverAgent.xcodeproj \ -scheme WebDriverAgentRunner \ -destination 'platform=iOS,id=<UDID>' \ -derivedDataPath ./DerivedData

命令执行后，WDA会作为XCTest Runner运行在设备上，并监听默认的HTTP端口。启动后验证服务是否正常：

curl http://localhost:8100/status

返回一段JSON数据，即表示WDA已经正常运行。在使用模拟器场景下，WDA可以直接通过Mac的本地端口访问；真机场景下，需要通过端口转发才能访问。这是下一步配置的重点。

6.3 如何确认WDA启动成功

如果对WDA启动是否成功有疑问，结合日志与设备上Runner应用的运行状态来判断：

1. 日志中出现了类似ServerURLHere->http://xx.xx.xx.xx:8100<-的启动信息，说明WDA已经开启了HTTP服务。
2. Xcode控制台没有任何报错，且日志持续处于等待状态。
3. 设备上能看到名为WebDriverAgentRunner的应用且处于前台运行状态。
4. curl请求/status返回JSON数据，HTTP状态码为200。

前三个都满足但最后一项curl不通时，通常问题出在端口转发配置上——模拟器环境不需要转发，真机环境必须配置。这是下一节的重点内容。

7. 端口转发配置与Appium连接

7.1 为什么要做端口转发

模拟器环境下，模拟器和Mac共享同一个网络栈，WDA的8100端口直接就能访问。真机环境下，设备有自己独立的网络栈，Mac上无法直接通过localhost:8100访问到真机上WDA的服务，需要做一层端口转发，把设备上WDA的8100端口映射到Mac的本地端口。

7.2 端口转发的两种操作方式

方式一：使用iproxy工具。

iproxy 8100 8100

执行后这个终端窗口会保持运行。第一个8100是Mac本地端口，第二个8100是设备上的端口。

方式二：使用Xcode自带的工具。

xcrun xctrace --device <UDID> \ --port 8100 \ --target-stdout - 2>/dev/null

使用方式和iproxy类似，都能实现端到端的转发。我实际使用中更喜欢iproxy，简单直接，无需记忆额外参数。

7.3 验证转发后的访问

转发生效后，在Mac的另一个终端执行：

curl http://localhost:8100/status

返回正常的JSON数据，说明链路已经打通：

{ "value": { "state": "success", "osVersion": "xx.x", "ios": { "ip": "xxx", "port": 8100 }, "ready": true } }

注意ready字段，值为true时Appium才能正常连接。

7.4 配置Appium连接参数

打开Appium客户端，配置capabilities：

{ "platformName": "iOS", "platformVersion": "15.4", "deviceName": "iPhone 12", "udid": "xxxxxxxx", "automationName": "XCUITest", "app": "/path/to/your.app" }

关键参数说明：

• automationName必须设为XCUITest，这是Appium在iOS上驱动WDA的方式。
• udid必须是当前连接设备对应的真实UDID。
• app指向被测App的路径，需要是已签名且可安装的.app包。

配置完成后，通过Appium客户端发起连接，正常情况下Appium会自动调用已安装的WDA，开始执行指定的自动化测试用例。

8. 真机测试中的若干补充问题排查清单

8.1 多台设备同时测试时的管理

同一台Mac连接多台iOS设备时，需要为每台设备单独执行WDA的部署和端口转发。端口转发配置需要错开，比如设备1映射8100，设备2映射8101，依次类推。Appium的capabilities中的udid参数也要对应调整。如果多设备执行的是同一套用例，建议每台设备的端口与udid用脚本统一管理，避免多终端手动操作引发混乱。

我在实际项目中会写一个简单的管理脚本，将所有设备的udid、端口、WDA编译路径都写在配置文件中，启动时统一读取。这种做法带来的直接收益是：团队其他成员接手时不需要理解底层细节，照着配置就能跑起来。

8.2 Runner应用缓存导致的行为异常

WDA代码更新后，设备上可能安装的还是旧版本Runner。排查方法：卸载设备上现有的WebDriverAgentRunner应用，重新安装新编译版本。

# 卸载已安装的Runner xcrun simctl uninstall booted com.facebook.WebDriverAgentRunner # 模拟器

真机卸载可以在设备上长按Runner应用图标，直接删除。删除后重新执行安装命令。这个操作建议作为每次更新WDA代码后的标准操作流程，能有效避免大量莫名其妙的“缓存问题”。

8.3 端口被占用时的处理思路

启动iproxy时提示端口已被占用，通常是因为之前启动的转发进程没有正常退出。排查方法：

lsof -i :8100

找到占用进程的PID后：

kill -9 <PID>

然后再重新启动iproxy。如果端口频繁被占用，建议整理一份端口分配表，避免进程残留。另外，Appium或Xcode本身也可能占用端口，执行前先做一次端口检查会更稳妥。

8.4 WDA启动后无法访问的排查路径

如果WDA看似正常启动，但curl始终无法访问，按照下面的顺序检查：

1. 确认Runner应用在设备上是前台运行状态。如果是后台运行，尝试手动切换回前台。
2. 确认Mac与设备在同一网络。
3. 确认防火墙没有拦截相关端口的通信。
4. 确认端口转发工具正常运行，且没有报错输出。
5. 设备重启或重置网络设置后，重新执行WDA的启动流程。

每一步执行时，优先查看WDA的日志输出。日志是最直观的定位线索，很多时候问题原因在日志中已经明确写出来了，只是容易被忽略。

8.5 常见问题速查表

为了方便日常排查，整理一份速查表，辅助定位问题：

9. WDA的日常维护与部署策略

9.1 WDA需要更新的时机

WDA不需要每次拿到源码更新就同步跟进。我总结需要更新的时机有三种：

1. iOS系统版本出现较重大升级，旧版WDA无法正常驱动。
2. Appium版本做了较大升级，要求对应版本的WDA配合。
3. 测试中发现具体操作在某版本上出现持续性问题，且后续版本修复了该问题。

除非以上情况，不建议频繁更新WDA。每次更新都意味着重新走一遍编译、部署、验证的完整流程，消耗时间。

9.2 给“测试用例跑不起来”的排查建议

WDA本身运行正常，但测试用例一直失败时，很大程度上不是WDA的问题，而是App与自动化机制的交互问题。排查建议：

1. 先执行一个最简单的用例（比如启动App后断言某个元素存在），确认基础链路是否打通。
2. 确认被测App在真机上能够正常启动，没有被签名或崩溃问题阻断。
3. 确认用例中使用的App包路径正确。
4. 查看Appium日志，定位是在会话建立阶段失败还是在具体步骤执行阶段失败。

9.3 环境文件的备份与自动化脚本

整套环境搭建完成后，建议将以下文件备份到团队共用的代码仓库中：

• 使用的版本组合记录（Xcode、Appium、WDA commit hash）。
• WDA源码的本地备份路径。
• 签名配置的Bundle ID记录。
• 已生成的编译产物压缩包。

我维护的项目中，将编译好的WebDriverAgentRunner-Runner.app打包上传到内部存储，新同事搭建环境时直接下载部署，节省大量重复编译时间。如果没有内部存储，也可以把编译好的目录压缩后保存，需要时再安装使用。注意同一产物只适用于签名时的同一开发者账号，换账号时需要重新编译。

10. 给新手的几条实操建议

WDA环境搭建是一项需要反复练习才能掌握的技能，我整理几条对新手有实际帮助的经验：

1. 第一次搭建时，完整记录每一步操作和报错信息。这些记录在后续排查问题过程中价值很大，比网上任何一个教程都贴近你的实际环境。
2. 遇到报错时，优先看完整的错误日志，不要只看末尾几行。很多失败原因都在日志的中间部分。我碰到过只看末尾报错信息完全找不到原因、但翻中间日志一眼就定位到问题的情况。
3. 尽量使用稳定的版本组合，不要追求最新。测试环境的稳定性是第一位的，新版本引入的变化往往需要时间沉淀。
4. 真机调试时，设备的屏幕保持常亮，不要锁定。设备锁屏会导致WDA的连接断开，测试直接中断。
5. 多准备一台备用真机。WDA的安装和运行可能影响设备上其他应用的状态，备用机可以在主设备出问题时保障测试进度。

最后分享一个我自己的习惯：每次搭建完环境，我会把当前环境跑一轮完整的基础用例，包括启动App、点击、输入、滑动、截屏这几类通用操作，确认所有核心能力都验证通过后再交付。这个习惯用很小的成本避免了后续用例执行时才发现环境问题的尴尬，你可以试试。