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

wangruofeng
0 阅读10分钟

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

iOS 模拟器管理完全指南封面_compressed.webp

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

命令速查表

运行时管理

命令功能
xcrun simctl list runtimes列出所有运行时
xcrun simctl runtime list列出可用运行时
xcrun simctl runtime add <path>添加运行时
xcrun simctl runtime delete <identifier>删除运行时（推荐）
xcrun simctl runtime delete --notUsedSinceDays <days>删除指定天数未使用的运行时

设备管理

命令功能
xcrun simctl list devices列出所有设备
xcrun simctl list devicetypes列出设备类型
xcrun simctl delete unavailable删除不可用设备
xcrun simctl create <name> <type> <runtime>创建新设备
xcrun simctl clone <UDID> <name>克隆设备
xcrun simctl rename <UDID> <name>重命名设备
xcrun simctl upgrade <UDID> <runtime>升级设备运行时

设备控制

命令功能
xcrun simctl boot <UDID>启动模拟器
xcrun simctl shutdown <UDID>关闭模拟器
xcrun simctl erase <UDID>重置模拟器
xcrun simctl ui <UDID> appearance <mode>切换主题模式

应用和数据

命令功能
xcrun simctl launch <UDID> <bundleID>启动应用
xcrun simctl terminate <UDID> <bundleID>关闭应用
xcrun simctl install <UDID> <path>安装应用
xcrun simctl uninstall <UDID> <bundleID>卸载应用
xcrun simctl get_app_container <UDID> <bundleID>获取应用容器路径
xcrun simctl privacy <UDID> grant all <bundleID>授予所有权限
xcrun simctl status_bar booted override --time <time>设置时间
xcrun simctl status_bar booted override --batteryLevel <level>设置电量
xcrun simctl status_bar booted clear清除状态栏修改

截图和录屏

命令功能
xcrun simctl io booted screenshot <file.png>截图
xcrun simctl io booted recordVideo <file.mp4>录制视频

高级功能

命令功能
xcrun simctl diagnose运行诊断
xcrun simctl getenv booted SIMULATOR_UDID获取当前模拟器 UDID
xcrun simctl openurl booted <url>打开 URL
xcrun simctl location booted set <lat,lon>设置模拟位置
xcrun simctl push booted <bundleID> <json>发送推送通知
xcrun simctl pbcopy <UDID>复制到剪贴板
xcrun simctl pbpaste <UDID>粘贴剪贴板内容
xcrun simctl keychain booted add-root-cert <path>添加证书到钥匙串
xcrun simctl addmedia booted <path>添加媒体文件
xcrun simctl icloud_sync booted触发 iCloud 同步
xcrun simctl logverbose booted enable/disable启用/禁用详细日志

高级用法

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 支持的所有子命令：

命令描述
addmedia添加照片、实时照片、视频或联系人到设备库
boot启动设备或设备对
clone克隆现有设备
create创建新设备
delete删除指定设备、不可用设备或所有设备
diagnose收集诊断信息和日志
erase擦除设备的内容和设置
get_app_container打印已安装应用的容器路径
getenv打印运行设备的环境变量
help打印给定子命令的使用说明
icloud_sync在设备上触发 iCloud 同步
install在设备上安装应用
install_app_data安装 xcappdata 包到设备，替换容器当前内容
io设置设备 IO 操作
keychain操作设备钥匙串
launch在设备上通过标识符启动应用
list列出可用设备、设备类型、运行时或设备对
location控制设备的模拟位置
logverbose启用或禁用设备的详细日志
openurl在设备中打开 URL
pair创建新手表和手机对
pair_activate将给定的对设置为活动
pbcopy将标准输入复制到设备剪贴板
pbpaste将设备剪贴板内容打印到标准输出
pbsync将剪贴板内容从一个剪贴板同步到另一个
privacy授予、撤销或重置隐私和权限
push发送模拟推送通知
rename重命名设备
runtime对运行时执行操作
shutdown关闭设备
spawn通过在设备上执行给定可执行文件来生成进程
status_bar设置或清除状态栏覆盖
terminate在设备上通过标识符终止应用
ui获取或设置 UI 选项
uninstall从设备卸载应用
unpair取消手表和手机对
upgrade将设备升级到更新的运行时

注意事项

  1. 权限问题：删除运行时通常需要 sudo 权限
  2. 设备依赖：删除运行时前确保没有设备在使用该运行时
  3. 磁盘空间：运行时占用较大磁盘空间（通常 10GB+），定期清理可释放空间
  4. Xcode 版本：不同 Xcode 版本支持的运行时版本可能不同
  5. JSON 输出：使用 -j 或 --json 参数便于脚本处理和数据分析
  6. UDID vs booted：
    • 使用 <UDID> 需要指定具体设备的唯一标识符
    • 使用 booted 自动选择当前启动的模拟器
    • 可以通过 xcrun simctl getenv booted SIMULATOR_UDID 获取当前启动设备的 UDID
  7. 应用 Bundle ID：大部分应用相关命令需要使用应用的 Bundle Identifier（如 com.example.app）
  8. 录制视频：录制过程中终端会被占用，使用 Ctrl+C 停止录制
avatar
文章
阅读
粉丝