AI_UIAutomation/iOS连接修复指南.md

iOS 真机连接问题修复指南

问题描述

连接 iOS 真机时遇到以下错误：

1. The port #8100 is occupied by an other process
2. Connection was refused to port 8100
3. WebDriverAgent (WDA) 无法在设备上启动

根本原因

iproxy 进程占用了 8100 端口，导致 Appium 无法启动 WDA

修复步骤

1. 确保设备已信任电脑

# 检查配对状态
idevicepair pair

如果提示需要信任对话框，请在手机上点击「信任」

2. 清理占用端口的进程

# 杀掉 iproxy 进程
pkill -f iproxy

3. 使用正确的 Appium 连接方式

错误方式（会导致端口冲突）：

driver = webdriver.Remote('http://127.0.0.1:4723/wd/hub', caps)

正确方式（使用 XCUITestOptions）：

from appium import webdriver
from appium.options.ios import XCUITestOptions

caps = XCUITestOptions()
caps.platform_name = 'iOS'
caps.platform_version = '26.3.1'  # 实际 iOS 版本
caps.device_name = 'iPhone'
caps.udid = '00008110-001A34303AE9801E'  # 设备 UDID
caps.bundle_id = 'com.demo.wohand'
caps.automation_name = 'XCUITest'
caps.set_capability('wdaLocalPort', 8200)  # 使用非8100端口

driver = webdriver.Remote('http://127.0.0.1:4723', options=caps)

4. 构建 WDA（可选，如果自动构建失败）

# 进入 WDA 目录
cd /Users/woan/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

# 构建 WDA（使用实际 iOS 版本）
xcodebuild -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination "id=YOUR_DEVICE_UDID" \
  IPHONEOS_DEPLOYMENT_TARGET=26.3.1 \
  -configuration Debug \
  build

iOS 版本问题

重要：配置中的 platform_version 必须与设备实际版本一致

• 查询设备版本：ideviceinfo | grep ProductVersion
• 当前测试设备：iOS 26.3.1（iPhone 14 Pro）
• 设备 UDID：00008110-001A34303AE9801E

常见错误

错误	解决方法
Port 8100 is occupied	杀掉 iproxy，使用其他端口
Please accept the trust dialog	手机上点击「信任」
WDA build failed	手动构建 WDA 后安装到设备
Connection refused	检查 WDA 是否在设备上运行

快速验证连接

# 测试 Appium 连接
python3 -c "
from appium import webdriver
from appium.options.ios import XCUITestOptions
caps = XCUITestOptions()
caps.platform_name = 'iOS'
caps.platform_version = '26.3.1'
caps.udid = '00008110-001A34303AE9801E'
caps.bundle_id = 'com.demo.wohand'
caps.automation_name = 'XCUITest'
caps.set_capability('wdaLocalPort', 8200)
driver = webdriver.Remote('http://127.0.0.1:4723', options=caps)
print('连接成功!')
driver.quit()
"