# 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. 确保设备已信任电脑

```bash
# 检查配对状态
idevicepair pair
```

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

### 2. 清理占用端口的进程

```bash
# 杀掉 iproxy 进程
pkill -f iproxy
```

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

**错误方式**（会导致端口冲突）：
```python
driver = webdriver.Remote('http://127.0.0.1:4723/wd/hub', caps)
```

**正确方式**（使用 XCUITestOptions）：
```python
from appium import webdriver
from appium.options.ios import XCUITestOptions

caps = XCUITestOptions()
caps.platform_name = 'iOS'
caps.platform_version = '26.5'  # 实际 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（可选，如果自动构建失败）

```bash
# 进入 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.5 \
  -configuration Debug \
  build
```

## iOS 版本问题

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

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

## 常见错误

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

## 快速验证连接

```bash
# 测试 Appium 连接
python3 -c "
from appium import webdriver
from appium.options.ios import XCUITestOptions
caps = XCUITestOptions()
caps.platform_name = 'iOS'
caps.platform_version = '26.5'
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()
"
```