using-xcode-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using Xcode CLI

使用Xcode CLI

Overview

概述

Native Xcode CLI tools (

xcodebuild

and

xcrun simctl

) provide full control over iOS/macOS builds and simulators without opening Xcode IDE. Core principle: Use CLI for automation, headless builds, and CI/CD—the same tools Xcode uses internally.

原生Xcode CLI工具（

xcodebuild

和

xcrun simctl

）无需打开Xcode IDE即可全面控制iOS/macOS应用的构建和模拟器。核心原则： 使用CLI实现自动化、无头构建以及CI/CD——这些都是Xcode内部使用的同款工具。

When to Use

适用场景

Building iOS/macOS apps from command line
Running apps in iOS Simulator programmatically
Taking screenshots or recording video of simulator
Running unit/UI tests with specific targeting
Automating builds in CI/CD pipelines
Managing simulator instances (boot, shutdown, erase)
Simulating location, push notifications, or permissions
Capturing app logs for debugging

Symptoms that trigger this skill:

"Unable to find destination matching"
"No scheme named X found"
"xcodebuild: error:"
Need to automate Xcode workflows
Building without opening Xcode IDE

从命令行构建iOS/macOS应用
以编程方式在iOS Simulator中运行应用
为模拟器截取屏幕截图或录制视频
针对特定目标运行单元/UI测试
在CI/CD流水线中自动化构建
管理模拟器实例（启动、关闭、重置）
模拟位置、推送通知或权限
捕获应用日志用于调试

触发使用该技能的典型场景：

"无法找到匹配的目标设备"
"未找到名为X的scheme"
"xcodebuild: error:"
需要自动化Xcode工作流
无需打开Xcode IDE即可构建应用

When NOT to Use

不适用场景

Editing code or project settings → Use Xcode IDE
Managing Swift Package dependencies → Use
```
swift package
```
CLI
Cross-platform builds → Use platform-specific tools
Signing/provisioning profile management → Use Xcode or fastlane

编辑代码或项目设置 → 使用Xcode IDE
管理Swift Package依赖 → 使用
```
swift package
```
CLI
跨平台构建 → 使用对应平台的专属工具
签名/描述文件管理 → 使用Xcode或fastlane

Quick Start

快速入门

Find available simulators:

bash

xcrun simctl list devices available

Build for simulator:

bash

UDID=$(xcrun simctl list devices --json | jq -r '.devices | .[].[] | select(.name=="iPhone 16 Pro" and .isAvailable==true) | .udid' | head -1)
xcodebuild -workspace App.xcworkspace -scheme App -destination "platform=iOS Simulator,id=$UDID" -derivedDataPath /tmp/build build

Install and launch:

bash

APP_PATH=$(find /tmp/build -name "*.app" -type d | head -1)
xcrun simctl install $UDID "$APP_PATH"
xcrun simctl launch --console $UDID com.bundle.identifier

Take screenshot:

bash

xcrun simctl io $UDID screenshot /tmp/screenshot.png

查找可用模拟器：

bash

xcrun simctl list devices available

为模拟器构建应用：

bash

UDID=$(xcrun simctl list devices --json | jq -r '.devices | .[].[] | select(.name=="iPhone 16 Pro" and .isAvailable==true) | .udid' | head -1)
xcodebuild -workspace App.xcworkspace -scheme App -destination "platform=iOS Simulator,id=$UDID" -derivedDataPath /tmp/build build

安装并启动应用：

bash

APP_PATH=$(find /tmp/build -name "*.app" -type d | head -1)
xcrun simctl install $UDID "$APP_PATH"
xcrun simctl launch --console $UDID com.bundle.identifier

截取屏幕截图：

bash

xcrun simctl io $UDID screenshot /tmp/screenshot.png

Quick Reference

快速参考

Task	Command
List schemes	`xcodebuild -workspace App.xcworkspace -list`
List simulators	`xcrun simctl list devices available`
Get simulator UDID	`xcrun simctl list devices --json \| jq ...`
Boot simulator	`xcrun simctl boot $UDID`
Build for simulator	`xcodebuild ... -destination "platform=iOS Simulator,id=$UDID" build`
Install app	`xcrun simctl install $UDID /path/to/App.app`
Launch app	`xcrun simctl launch --console $UDID com.bundle.id`
Take screenshot	`xcrun simctl io $UDID screenshot /tmp/shot.png`
Run tests	`xcodebuild ... test`
Stream logs	`/usr/bin/log stream --predicate 'processImagePath CONTAINS "App"'`

任务	命令
列出scheme	`xcodebuild -workspace App.xcworkspace -list`
列出模拟器	`xcrun simctl list devices available`
获取模拟器UDID	`xcrun simctl list devices --json \| jq ...`
启动模拟器	`xcrun simctl boot $UDID`
为模拟器构建应用	`xcodebuild ... -destination "platform=iOS Simulator,id=$UDID" build`
安装应用	`xcrun simctl install $UDID /path/to/App.app`
启动应用	`xcrun simctl launch --console $UDID com.bundle.id`
截取屏幕截图	`xcrun simctl io $UDID screenshot /tmp/shot.png`
运行测试	`xcodebuild ... test`
流式传输日志	`/usr/bin/log stream --predicate 'processImagePath CONTAINS "App"'`

Reference Documentation

参考文档

Reference	Contents
xcodebuild.md	Project discovery, building, archiving, testing
simctl.md	Device management, screenshots, video, location, permissions
logging.md	Log streaming and filtering predicates
workflows.md	End-to-end automation scripts

参考链接	内容
xcodebuild.md	项目发现、构建、归档、测试
simctl.md	设备管理、截图、视频、位置、权限
logging.md	日志流式传输与过滤谓词
workflows.md	端到端自动化脚本

Common Patterns

常见模式

Build + Run

构建 + 运行

Find simulator UDID via
```
simctl list devices --json
```
Boot simulator with
```
simctl boot $UDID
```
Build with
```
xcodebuild
```
using
```
-derivedDataPath
```
Find .app bundle in derived data
Install with
```
simctl install
```
Launch with
```
simctl launch --console
```

通过
```
simctl list devices --json
```
查找模拟器UDID
使用
```
simctl boot $UDID
```
启动模拟器
使用
```
xcodebuild
```
并指定
```
-derivedDataPath
```
进行构建
在派生数据中查找.app包
使用
```
simctl install
```
安装应用
使用
```
simctl launch --console
```
启动应用

Run Tests

运行测试

bash

xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  -only-testing "AppTests/SpecificTest" test

bash

xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  -only-testing "AppTests/SpecificTest" test

Common Mistakes

常见错误

Mistake	Fix
"Unable to find destination"	Verify simulator exists with `simctl list devices` . Use exact name or UDID.
"No scheme found"	Run `xcodebuild -list` to see available schemes. Ensure you're using `-workspace` or `-project` flag.
"App not found after build"	Use `-derivedDataPath /tmp/build` and search there with `find` .
Simulator not responding	Try `xcrun simctl shutdown all` then boot fresh.
Build succeeds but app crashes	Check `xcrun simctl launch --console` for runtime errors.
Tests hang indefinitely	Add `-destination-timeout` flag. Ensure simulator is booted first.
Wrong simulator selected	Always use UDID from `simctl list devices --json` , not device name alone.
Stale build artifacts	Use `clean build` action or delete derived data directory.

错误	解决方法
"无法找到目标设备"	使用 `simctl list devices` 验证模拟器是否存在，使用精确名称或UDID。
"未找到scheme"	运行 `xcodebuild -list` 查看可用scheme，确保使用了 `-workspace` 或 `-project` 参数。
"构建后未找到应用"	使用 `-derivedDataPath /tmp/build` 并通过 `find` 命令在该路径下查找。
模拟器无响应	尝试执行 `xcrun simctl shutdown all` 后重新启动模拟器。
构建成功但应用崩溃	查看 `xcrun simctl launch --console` 输出获取运行时错误信息。
测试无限期挂起	添加 `-destination-timeout` 参数，确保模拟器已预先启动。
选择了错误的模拟器	始终使用 `simctl list devices --json` 返回的UDID，而非仅依赖设备名称。
构建产物过期	使用 `clean build` 操作或删除派生数据目录。