用 xcrun simctl 脚本化管理 iOS 模拟器与…

在需要脚本化 iOS 模拟器工作流、调试 CoreSimulator 启动失败，或判断哪些硬件/性能/网络/内存/安全行为必须用真机验证时使用。

适用场景

解决思路

1. 用 `xcrun simctl list devices available` 列出按 runtime 分组的模拟器，`xcrun simctl list runtimes` 列出已安装 runtime，`xcrun simctl list devices booted` 只列已启动设备，`xcrun simctl list -j devices available` 输出 JSON 供脚本解析。
2. 用 `xcrun simctl list devicetypes` 和 `xcrun simctl list runtimes` 查找可用标识符，再用 `xcrun simctl create "My Test Phone" "iPhone 16 Pro" "com.apple.CoreSimulator.SimRuntime.iOS-18-4"` 创建设备并记录返回的 UDID。
3. 生命周期管理：`xcrun simctl boot <UDID>` 启动，`xcrun simctl bootstatus <UDID> -b` 启动并等待就绪，`xcrun simctl shutdown <UDID>` 关闭，`xcrun simctl erase <UDID>` 恢复出厂（保留设备），`xcrun simctl delete <UDID>` 删除设备，`xcrun simctl delete unavailable` 删除当前 Xcode 不可用设备，`xcrun simctl shutdown all` 关闭全部。
4. 仅当只有一个模拟器运行时可用 `booted` 作为 UDID 简写；多个模拟器同时启动时 `booted` 会不确定地选一个，并行场景应显式使用 UDID。
5. 脚本和 CI 中把 `xcrun simctl bootstatus <UDID> -b` 作为 install、launch、push、location 之前的规范启动与就绪门禁。
6. 安装 App：先用 `xcodebuild build -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16 Pro' -derivedDataPath build/` 构建，再 `xcrun simctl bootstatus <UDID> -b`，最后 `xcrun simctl install <UDID> build/Build/Products/Debug-iphonesimulator/MyApp.app`；路径必须指向为模拟器架构构建的 `.app` 目录，而非 `.ipa`。
7. 启动与终止：`xcrun simctl launch booted com.example.MyApp` 按 bundle ID 启动，`xcrun simctl launch --console booted com.example.MyApp` 同时把 stdout/stderr 流到终端，`xcrun simctl launch booted com.example.MyApp --reset-onboarding -AppleLanguages "(fr)"` 传启动参数，`xcrun simctl terminate booted com.example.MyApp` 终止。
8. 查看容器路径：`xcrun simctl get_app_container booted com.example.MyApp app` 取 App bundle 位置，`... data` 取数据容器（Documents、Library、tmp），`... group.com.example.shared` 取共享 App Group 容器。
9. 推送模拟：创建含 `aps`（alert/badge/sound）和自定义键的 JSON payload 文件，用 `xcrun simctl push booted com.example.MyApp payload.json` 发送，或用 `echo '{"aps":{"alert":"Quick test"}}' | xcrun simctl push booted com.example.MyApp -` 从 stdin 管道传入；这只测试本地 payload 处理与通知 UI，不测试 APNs 投递。
10. 位置模拟：`xcrun simctl location booted set 37.3349,-122.0090` 设固定坐标，`xcrun simctl location booted list` 列出预定义场景，`xcrun simctl location booted run "City Run"` 运行预定义场景，`xcrun simctl location booted start --speed=15 --interval=1 37.3349,-122.0090 37.3317,-122.0307` 按自定义航点行进，`printf "37.3349,-122.0090\n37.3317,-122.0307\n" | xcrun simctl location booted start --distance=100 -` 从 stdin 读航点，`xcrun simctl location booted clear` 清除。
11. 区分位置命令边界：`simctl location run` 只接受内置场景名（如 "City Run"、"Freeway Drive"），不接受 GPX 文件路径；自定义坐标航点用 `simctl location start`；GPX 路线用 Xcode 的 Debug > Simulate Location 菜单。
12. 位置模拟会影响已启动设备上所有使用 Core Location 的 App，测试完成后要清除位置以免影响后续测试结果。
13. 隐私权限：`xcrun simctl privacy booted grant photos com.example.MyApp` 授予，`... revoke microphone com.example.MyApp` 撤销，`... reset all com.example.MyApp` 重置全部；常见服务名有 `photos`、`microphone`、`contacts`、`calendar`、`reminders`、`location`、`location-always`、`motion`、`siri`。
14. 在 CI 中预授予权限可避免系统权限弹窗阻塞自动化测试，但会掩盖缺失的用途描述键；必须保留 Info.plist 中必需的隐私字符串，并仍然测试正常弹窗流程。
15. 深链与 URL：`xcrun simctl openurl booted "https://example.com/product/123"` 触发通用链接，`xcrun simctl openurl booted "myapp://settings/notifications"` 触发自定义 URL scheme；通用链接需配置 App 的 associated domains entitlement，模拟器使用域名上的 `apple-app-site-association` 文件。
16. 状态栏覆盖：`xcrun simctl status_bar booted override --time "9:41" --batteryState charged --batteryLevel 100 --cellularMode active --cellularBars 4 --wifiBars 3 --operatorName ""` 生成干净状态栏，`xcrun simctl status_bar booted clear` 清除全部覆盖；用于生成一致的 App Store 截图，截图后务必清除以免干扰其他测试。
17. 截图与录屏：`xcrun simctl io booted screenshot screenshot.png` 截图，`xcrun simctl io booted recordVideo recording.mov` 录屏（Ctrl+C 停止），`xcrun simctl io booted screenshot --mask black screenshot.png` 带显示遮罩截图；`--mask` 可选 `ignored`（默认无遮罩）、`alpha`（透明圆角）、`black`（黑色圆角），`alpha` 仅支持截图，录屏会回退为 `black`。
18. 录屏持续到进程收到 SIGINT（Ctrl+C）才停止，且只有停止后才保存文件；用 SIGKILL 杀死进程会丢失文件。
19. 日志流：`xcrun simctl spawn booted log stream --level debug` 流式输出 debug 及以上日志，`--predicate 'subsystem == "com.example.app"'` 按 subsystem 过滤，`--predicate 'subsystem == "com.example.app" AND category == "networking"'` 按 subsystem 和 category 过滤，`--predicate 'process == "MyApp"'` 按进程名过滤。
20. 编译期模拟器检测：用 `#if targetEnvironment(simulator)` 排除模拟器无法运行的代码（如跳过 APNs 注册），优先于运行时检测（如检查 `ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"]`），因为编译器会完全剥离被排除代码，避免不可用符号的链接错误。
21. 模拟器能力限制（权威分类）：APNs 推送投递不支持（用 `simctl push` 本地模拟）；性能保真度仅为相对值，CPU/处理性能、网络速度、图形/Metal、内存带宽、帧时序、内存压力、Jetsam、shader 正确性、热行为均不准确，性能敏感工作需在真机验证；Metal GPU family 仅部分一致（用宿主 Mac GPU 而非设备 GPU）；相机硬件不支持（用照片库注入或 mock `AVCaptureSession`）；音频输入/麦克风无通用 App 音频输入（Siri 可从模拟器菜单激活）；Secure Enclave 不支持（`kSecAttrTokenIDSecureEnclave` 操作失败）；App Attest（DCAppAttestService）不支持（`isSupported` 返回 `false`）；DockKit 电机控制不支持；加速度计/陀螺仪不支持（运动相关行为用真机）；气压计不支持；NFC（Core NFC）不支持；蓝牙（Core Bluetooth）不支持（BLE 测试用真机）；CarPlay 显示模拟通过模拟器外部显示/CarPlay 选项支持，但仍需在车机或设备环境验证；Face ID/Touch ID 无硬件（用 Features > Face ID / Touch ID 菜单）；内存警告、位置变化、手动 iCloud 同步触发可通过模拟器菜单或 `simctl` 支持，手动同步可测试 App 回调处理；自动 iCloud 传播与冲突需真机（真实账号/设备、通知触发同步、后台投递、冲突、账号/设备状态差异）；蜂窝网络条件不支持（用 Mac 上的 Network Link Conditioner）。
22. 不要在脚本中硬编码模拟器 UDID：UDID 会随模拟器删除重建而变化，硬编码会在其他机器和 CI 上失效；应通过 `xcrun simctl list -j devices available | jq -r '.devices["com.apple.CoreSimulator.SimRuntime.iOS-18-4"][] | select(.name == "iPhone 16 Pro") | .udid'` 按名称和 runtime 查找，或仅有一个模拟器时用 `booted`。
23. 不要在已关闭的模拟器上 install 或 launch：`simctl install` 和 `simctl launch` 需要已启动设备，否则会静默失败或报无帮助错误；应先 `xcrun simctl bootstatus <UDID> -b` 再 install 和 launch。
24. 不要在 CI 中留下僵尸模拟器：每个已启动模拟器都消耗内存和 CPU，创建后不清理会累积；应在 teardown 中用 `cleanup() { xcrun simctl shutdown all; xcrun simctl delete "$UDID"; }` 配合 `trap cleanup EXIT` 清理。
25. 不要对卡住的模拟器反复重试 boot：卡在 "Booting" 状态的模拟器不会因重试 `boot` 恢复，底层 CoreSimulator 状态已损坏；应 `xcrun simctl shutdown "$UDID"`、`xcrun simctl erase "$UDID"`、再 `xcrun simctl boot "$UDID"`；若仍失败则 `xcrun simctl shutdown all`、`xcrun simctl erase all`，最后手段是 `rm -rf ~/Library/Developer/CoreSimulator/Caches`。
26. 评审清单：设备用显式 device type 和 runtime 标识符创建；脚本用 `booted` 或从 JSON 解析的 UDID 而非硬编码；开发期用 `simctl push` 测试推送 payload；发布前在真机验证推送投递；位置模拟覆盖固定坐标、预定义场景和自定义航点；CI 中预授予隐私权限避免阻塞弹窗；对模拟器不可用 API 加 `#if targetEnvironment(simulator)` 守卫；截图后清除状态栏覆盖；CI 在 teardown 中关闭并删除模拟器；日志流配置 subsystem/category 谓词以聚焦调试；调试时用 App 容器路径检查沙盒数据。

适用边界 · 注意事项

• 需要验证 APNs 真实投递、相机/麦克风/运动传感器/NFC/蓝牙/Secure Enclave/App Attest 等模拟器不支持的硬件能力时，必须使用真机。
• 需要评估 CPU/GPU/网络/内存带宽/帧时序/内存压力/Jetsam/热行为等性能保真度时，模拟器结果不可信，应在真机验证。
• 需要测试自动 iCloud 传播与冲突、真实蜂窝网络条件等依赖真实账号/设备/网络状态的行为时，模拟器不适用。