debugger-agent

iOS 调试 Agent

概述

在已启动的模拟器上构建并运行 iOS 项目、与 UI 交互，并捕获日志以进行调试。

前置条件

• 已安装 Xcode 和命令行工具
• 已启动的 iOS 模拟器（使用 xcrun simctl list devices 检查）
• 包含 .xcodeproj 或 .xcworkspace 的项目

核心工作流

1) 查找已启动的模拟器

xcrun simctl list devices | grep -E "Booted"

如果没有已启动的模拟器，请让用户启动一个：

xcrun simctl boot "iPhone 15 Pro"

2) 构建项目

对于工作区：

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build

对于项目：

xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build

3) 安装并启动应用

查找构建好的应用：

find ~/Library/Developer/Xcode/DerivedData -name "*.app" -path "*Debug-iphonesimulator*" | head -1

在模拟器上安装：

xcrun simctl install booted /path/to/MyApp.app

启动应用：

xcrun simctl launch booted com.example.MyApp

4) 捕获日志

流式传输应用日志：

xcrun simctl spawn booted log stream --predicate 'subsystem == "com.example.MyApp"' --level debug

或者捕获所有模拟器日志：

xcrun simctl spawn booted log stream --level debug

UI 交互

截取屏幕截图

xcrun simctl io booted screenshot screenshot.png

录制视频

xcrun simctl io booted recordVideo video.mp4
# Press Ctrl+C to stop recording

在模拟器中打开 URL

xcrun simctl openurl booted "myapp://deeplink"

发送推送通知

xcrun simctl push booted com.example.MyApp notification.apns

故障排除

• 构建失败：使用 xcodebuild -list 检查方案名称
• 应用无法启动：使用 defaults read /path/to/MyApp.app/Info.plist CFBundleIdentifier 验证 Bundle ID
• 未找到模拟器：使用 xcrun simctl list devices available 列出可用模拟器
• 清理构建：运行 xcodebuild clean 或删除 DerivedData

常用命令参考

任务	命令
列出模拟器	xcrun simctl list devices
启动模拟器	xcrun simctl boot "iPhone 15 Pro"
关闭模拟器	xcrun simctl shutdown booted
抹掉模拟器	xcrun simctl erase booted
安装应用	xcrun simctl install booted /path/to/App.app
卸载应用	xcrun simctl uninstall booted com.example.app
启动应用	xcrun simctl launch booted com.example.app
终止应用	xcrun simctl terminate booted com.example.app
获取应用容器	xcrun simctl get_app_container booted com.example.app