iOS 模拟器管理完全指南：xcrun simctl 从入门到精通

发布于 2026年02月06日 09:10

#iOS#CLI

本文档记录了开发过程中常用的 xcrun simctl 命令，用于管理 iOS 模拟器和运行时环境。

xcrun 是 macOS 上的一个命令行工具，用于在命令行中执行 Xcode 开发工具链中的各种工具和实用程序，而无需直接指定其完整路径。这使得在终端中更轻松地调用和管理 Xcode 相关的工具。

运行时管理

列出所有运行时

xcrun simctl list runtimes

说明：显示所有已安装的 iOS、watchOS、tvOS 等运行时环境，包括运行时版本、构建号和唯一标识符。

列出可用的运行时

xcrun simctl list runtimes available

说明：仅显示当前可用的运行时，过滤掉不可用的版本。

JSON 格式输出

# 输出为 JSON 格式（适合脚本处理）
xcrun simctl list runtimes -j
xcrun simctl runtime list --json

添加运行时

xcrun simctl runtime add "path/to/Simulator_Runtime.dmg"

说明：安装指定的运行时环境。需要从 Apple 开发者网站下载对应的 .dmg 文件。

删除运行时

# 推荐方式
xcrun simctl runtime delete com.apple.CoreSimulator.SimRuntime.iOS-18-2

# 删除指定天数未使用的运行时
xcrun simctl runtime delete --notUsedSinceDays 30

# 预览将要删除的内容（不实际删除）
xcrun simctl runtime delete com.apple.CoreSimulator.SimRuntime.iOS-18-2 --dry-run

常见运行时标识符：

• com.apple.CoreSimulator.SimRuntime.iOS-18-2
• com.apple.CoreSimulator.SimRuntime.iOS-17-5
• com.apple.CoreSimulator.SimRuntime.tvOS-18-1

设备管理

列出和筛选设备

# 列出设备和运行时
xcrun simctl list devices
xcrun simctl list runtimes

# 列出设备类型（默认行为）
xcrun simctl list

# 输出为 JSON 格式
xcrun simctl list devices --json

# 获取所有的设备（包含真机）使用 xctrace
xcrun xctrace list devices

# 筛选特定版本的设备
xcrun simctl list devices | grep -A 20 "iOS 18.2"

# 列出设备类型
xcrun simctl list devicetypes

说明：

• 不带参数的 list 默认显示设备类型
• 使用 list devices 显示已创建的模拟器设备
• 使用 list runtimes 显示运行时环境
• 使用 grep 筛选特定 iOS 版本的设备，-A 20 表示显示匹配行及后续 20 行

设备操作

# 删除不可用的设备
xcrun simctl delete unavailable

# 创建新设备
xcrun simctl create "My iPhone 15" "iPhone 15" "iOS18.2"

# 克隆现有设备
xcrun simctl clone <sourceUDID> "New Device Name"

# 重命名设备
xcrun simctl rename <UDID> "New Device Name"

# 升级设备到新运行时
xcrun simctl upgrade <UDID> <runtime_identifier>

设备控制

# 打开上次启动的模拟器
open -a simulator

# 启动指定模拟器
xcrun simctl boot <UDID>

# 关闭指定模拟器
xcrun simctl shutdown <UDID>

# 重置指定模拟器
xcrun simctl erase <UDID>

# 清除所有 iOS 模拟器缓存
xcrun simctl erase all

# 切换主题模式
xcrun simctl ui <UDID> appearance light  # 浅色主题
xcrun simctl ui <UDID> appearance dark   # 深色主题

应用和数据管理

应用安装和启动

# 安装应用
xcrun simctl install <UDID> <path/to/app.app>

# 启动指定应用
xcrun simctl launch booted <packageName>
xcrun simctl launch <UDID> <packageName>

# 关闭已打开的应用
xcrun simctl terminate booted <packageName>
xcrun simctl terminate <UDID> <packageName>

# 卸载应用
xcrun simctl uninstall <UDID> <bundleIdentifier>

# 获取应用容器路径
xcrun simctl get_app_container <UDID> <bundleIdentifier>

# 安装应用数据
xcrun simctl install_app_data <UDID> <path/to/data.xcappdata>

隐私和权限管理

# 授予所有权限
xcrun simctl privacy booted grant all <packageName>

# 授予特定权限
xcrun simctl privacy booted grant photos <packageName>

# 撤销权限
xcrun simctl privacy booted revoke camera <packageName>

# 重置权限
xcrun simctl privacy booted reset all <packageName>

状态栏控制

# 设置时间
xcrun simctl status_bar booted override --time 23:59

# 设置电量为50
xcrun simctl status_bar booted override --batteryLevel 50

# 设置数据网络类型
xcrun simctl status_bar booted override --dataNetwork 5g

# 设置 WiFi 信号栏（0-3）
xcrun simctl status_bar booted override --wifiBars 3

# 设置运营商名称
xcrun simctl status_bar booted override --operatorName '中国电信'

# 清除所有修改
xcrun simctl status_bar booted clear

截图和录屏

booted 代表当前启动的模拟器；也可指定模拟器 <UDID>

# 截图
xcrun simctl io booted screenshot xxx.png
xcrun simctl io <UDID> screenshot xxx.png

# 录制模拟器视频（在终端按 Ctrl+C 来停止录屏）
xcrun simctl io booted recordVideo test.mp4

# 保存到指定目录
xcrun simctl io booted screenshot ~/Desktop/screenshot.png
xcrun simctl io booted screenshot /Users/username/Pictures/screenshot.png

高级功能

剪贴板操作

# 复制到剪贴板
echo "Hello" | xcrun simctl pbcopy <UDID>

# 粘贴剪贴板内容
xcrun simctl pbpaste <UDID>

# 在设备间同步剪贴板内容
xcrun simctl pbsync <sourceUDID> <destinationUDID>

URL 和位置

# 打开 URL
xcrun simctl openurl booted "https://www.example.com"

# 设置模拟位置
xcrun simctl location booted set 37.7749,-122.4194

# 清除模拟位置
xcrun simctl location booted clear

推送通知

# 发送模拟推送通知
xcrun simctl push booted <bundleIdentifier> <path/to/push.json>

推送通知 JSON 示例：

{
  "aps": {
    "alert": "Test Push Notification",
    "badge": 1,
    "sound": "default"
  }
}

Keychain 和媒体文件

# 添加钥匙条目
xcrun simctl keychain booted add-root-cert <path/to/cert.der>

# 删除钥匙串
xcrun simctl keychain booted reset

# 添加照片到设备
xcrun simctl addmedia booted ~/Photos/photo.jpg

# 添加视频到设备
xcrun simctl addmedia booted ~/Videos/video.mp4

环境变量和系统信息

# 获取启动的模拟器 UDID
xcrun simctl getenv booted SIMULATOR_UDID

# 获取环境变量
xcrun simctl getenv <UDID> <variable_name>

# 读取所有 iOS 模拟器的信息
defaults read com.apple.iphonesimulator

# 触发 iCloud 同步
xcrun simctl icloud_sync booted

# 启用详细日志
xcrun simctl logverbose booted enable

# 禁用详细日志
xcrun simctl logverbose booted disable

诊断工具

# 基本诊断
xcrun simctl diagnose

# 指定输出目录
xcrun simctl diagnose --output ~/Desktop/diag

# 包含所有设备日志
xcrun simctl diagnose --all-logs

# 不创建压缩包
xcrun simctl diagnose --no-archive

# 无超时运行
xcrun simctl diagnose -X

说明：生成模拟器诊断报告，用于排查模拟器问题和故障。常用参数：

• --output: 指定输出目录
• --all-logs: 包含所有设备日志
• --no-archive: 不创建压缩包
• -X: 无超时运行（忽略超时设置）

常见使用场景

场景 1：清理旧版本运行时

当需要升级到新的 iOS 版本时，可以删除旧运行时以释放空间：

# 1. 查看当前运行时
xcrun simctl list runtimes

# 2. 删除不需要的运行时
sudo xcrun simctl runtime delete com.apple.CoreSimulator.SimRuntime.iOS-18-2

# 3. 确认删除成功
xcrun simctl list runtimes

场景 2：清理无效设备

定期清理失效的模拟器设备：

# 1. 查看所有设备
xcrun simctl list

# 2. 删除不可用的设备
xcrun simctl delete unavailable

# 3. 验证清理结果
xcrun simctl list

场景 3：检查特定版本的设备

查找使用特定 iOS 版本的设备：

# 查找 iOS 18.2 的设备
xcrun simctl list devices | grep -A 20 "iOS 18.2"

# 使用 JSON 和 jq 进行更精确的过滤
xcrun simctl list devices --json | jq '.devices'

场景 4：批量清理旧运行时

定期清理未使用的运行时以释放磁盘空间：

# 1. 查看所有运行时（详细信息）
xcrun simctl runtime list -v

# 2. 预览将要删除的运行时（安全模式）
xcrun simctl runtime delete --notUsedSinceDays 30 --dry-run

# 3. 删除 30 天未使用的运行时
xcrun simctl runtime delete --notUsedSinceDays 30

# 4. 确认清理结果
xcrun simctl list runtimes

场景 5：自动化测试截图

在自动化测试中截取屏幕截图：

# 启动模拟器
xcrun simctl boot <UDID>

# 安装应用
xcrun simctl install <UDID> /path/to/app.app

# 启动应用
xcrun simctl launch <UDID> com.example.app

# 等待应用加载...

# 截图
xcrun simctl io <UDID> screenshot screenshot.png

# 录制视频
xcrun simctl io <UDID> recordVideo demo.mp4

场景 6：模拟不同状态栏状态

测试应用在不同状态栏状态下的表现：

# 模拟低电量
xcrun simctl status_bar booted override --batteryLevel 10

# 模拟特定时间
xcrun simctl status_bar booted override --time 23:59

# 模拟无信号
xcrun simctl status_bar booted override --wifiBars 0

# 测试完成后清除
xcrun simctl status_bar booted clear

场景 7：测试推送通知

# 创建推送通知文件
cat > push.json << EOF
{
  "aps": {
    "alert": {
      "title": "新消息",
      "body": "您有一条新消息"
    },
    "badge": 1,
    "sound": "default"
  }
}
EOF

# 发送推送通知
xcrun simctl push booted com.example.app push.json

命令速查表

运行时管理

设备管理

设备控制

应用和数据

截图和录屏

高级功能

高级用法

JSON 输出和脚本化处理

所有 list 命令都支持 JSON 输出，适合脚本化处理：

# 输出运行时为 JSON 格式
xcrun simctl list runtimes -j

# 输出设备列表为 JSON 格式
xcrun simctl list devices --json

# 使用 jq 进行过滤和格式化
xcrun simctl list runtimes -j | jq '.runtimes[] | select(.name | contains("iOS"))'

# 获取所有设备 UDID
xcrun simctl list devices --json | jq -r '.devices | to_entries[] | .value[] | .udid'

# 获取所有已启动的设备
xcrun simctl list devices --json | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid'

# 获取特定运行时的所有设备
xcrun simctl list devices --json | jq -r '.devices | to_entries[] | .value[] | select(.runtime.identifier | contains("iOS18-2")) | .name'

完整命令参考

xcrun simctl 支持的所有子命令：

注意事项

1. 权限问题：删除运行时通常需要 sudo 权限

2. 设备依赖：删除运行时前确保没有设备在使用该运行时

3. 磁盘空间：运行时占用较大磁盘空间（通常 10GB+），定期清理可释放空间

4. Xcode 版本：不同 Xcode 版本支持的运行时版本可能不同

5. JSON 输出：使用 -j 或 --json 参数便于脚本处理和数据分析

6. UDID vs booted：

   1. 使用 <UDID> 需要指定具体设备的唯一标识符

   2. 使用 booted 自动选择当前启动的模拟器

   3. 可以通过 xcrun simctl getenv booted SIMULATOR_UDID 获取当前启动设备的 UDID

7. 应用 Bundle ID：大部分应用相关命令需要使用应用的 Bundle Identifier（如 com.example.app）

8. 录制视频：录制过程中终端会被占用，使用 Ctrl+C 停止录制