Xcode Build Direct

Xcode 直接构建

Build and manage iOS/macOS projects using native Xcode CLI tools instead of MCP servers.

使用Xcode原生CLI工具（而非MCP服务器）构建和管理iOS/macOS项目。

When to Use This Skill

适用场景

Use this skill when:

Building iOS or macOS apps with Xcode
Running apps in iOS simulators
Managing simulator instances (boot, shutdown, list)
Taking screenshots of simulators
Capturing app logs
Running tests (unit or UI)
Automating UI interactions (tap, type, swipe)

Preference: Always use direct CLI commands (

xcodebuild

,

xcrun simctl

) instead of XcodeBuildMCP tools.

本技能适用于以下场景：

使用Xcode构建iOS或macOS应用
在iOS模拟器中运行应用
管理模拟器实例（启动、关闭、列出）
截取模拟器屏幕截图
捕获应用日志
运行测试（单元测试或UI测试）
自动化UI交互（点击、输入、滑动）

优先建议：始终使用原生CLI命令（

xcodebuild

、

xcrun simctl

）替代XcodeBuildMCP工具。

Quick Start

快速开始

1. Discover Project Structure

1. 探查项目结构

bash

undefined

bash

undefined

List schemes in a workspace

列出工作区中的scheme

xcodebuild -workspace /path/to/App.xcworkspace -list

List schemes in a project

列出项目中的scheme

xcodebuild -project /path/to/App.xcodeproj -list

Show build settings

查看构建设置

xcodebuild -workspace /path/to/App.xcworkspace -scheme AppScheme -showBuildSettings

undefined

xcodebuild -workspace /path/to/App.xcworkspace -scheme AppScheme -showBuildSettings

undefined

2. Find Available Simulators

2. 查找可用模拟器

bash

undefined

bash

undefined

List all simulators

列出所有模拟器

xcrun simctl list devices

List as JSON (better for parsing)

以JSON格式列出（更便于解析）

xcrun simctl list devices --json

List only available simulators

仅列出可用模拟器

xcrun simctl list devices available

undefined

xcrun simctl list devices available

undefined

3. Build for Simulator

3. 为模拟器构建应用

bash

undefined

bash

undefined

Get simulator UUID first

先获取模拟器UUID

Build

执行构建

xcodebuild
-workspace /path/to/App.xcworkspace
-scheme AppScheme
-destination "platform=iOS Simulator,id=$UDID"
-configuration Debug
-derivedDataPath /tmp/build
build

undefined

xcodebuild
-workspace /path/to/App.xcworkspace
-scheme AppScheme
-destination "platform=iOS Simulator,id=$UDID"
-configuration Debug
-derivedDataPath /tmp/build
build

undefined

4. Install and Launch

4. 安装并启动应用

bash

undefined

bash

undefined

Find the built .app

查找构建好的.app文件

APP_PATH=$(find /tmp/build -name "*.app" -type d | head -1)

Install on simulator

在模拟器上安装应用

xcrun simctl install $UDID "$APP_PATH"

Launch app

启动应用

xcrun simctl launch $UDID com.your.bundleid

undefined

xcrun simctl launch $UDID com.your.bundleid

undefined

5. Take Screenshot

5. 截取屏幕截图

bash

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

bash

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

Detailed References

详细参考文档

For comprehensive command documentation, see:

CLI_REFERENCE.md - Full
```
xcodebuild
```
and
```
xcrun simctl
```
command reference
XCUITEST_GUIDE.md - UI automation via XCUITest (tap, type, gestures, element queries)

如需完整的命令说明，请查看：

CLI_REFERENCE.md -
```
xcodebuild
```
和
```
xcrun simctl
```
的完整命令参考
XCUITEST_GUIDE.md - 基于XCUITest的UI自动化（点击、输入、手势、元素查询）

Common Patterns

常用操作流程

Build + Run Workflow

构建+运行流程

bash

undefined

bash

undefined

1. Boot simulator

1. 启动模拟器

xcrun simctl boot $UDID 2>/dev/null || true

2. Build

2. 执行构建

xcodebuild -workspace App.xcworkspace -scheme App
-destination "platform=iOS Simulator,id=$UDID"
-derivedDataPath /tmp/build build

3. Find and install app

3. 查找并安装应用

APP=$(find /tmp/build -name "*.app" -type d | head -1) xcrun simctl install $UDID "$APP"

4. Launch with console output

4. 启动应用并输出控制台日志

xcrun simctl launch --console $UDID com.bundle.id

undefined

xcrun simctl launch --console $UDID com.bundle.id

undefined

Log Capture

日志捕获

bash

undefined

bash

undefined

Stream app logs (run in background)

流式输出应用日志（后台运行）

/usr/bin/log stream
--predicate 'processImagePath CONTAINS[cd] "AppName"'
--style json & LOG_PID=$!

... interact with app ...

... 与应用进行交互 ...

Stop logging

停止日志捕获

kill $LOG_PID

undefined

kill $LOG_PID

undefined

Running Tests

运行测试

bash

undefined

bash

undefined

Unit tests

单元测试

xcodebuild -workspace App.xcworkspace -scheme App
-destination "platform=iOS Simulator,id=$UDID"
test

Specific test class

指定测试类

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

undefined

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

undefined

UI Automation

UI自动化

For tapping, typing, and UI element queries, use XCUITest (Apple's native UI testing framework).

This is more powerful than MCP-based automation because:

Native to iOS, always up-to-date
Full access to accessibility tree
Can wait for elements, handle animations
Integrates with Xcode test runner

See XCUITEST_GUIDE.md for complete patterns.

Quick example:

swift

// In a UI test file
func testLogin() {
    let app = XCUIApplication()
    app.launch()

    // Type in text field
    app.textFields["email"].tap()
    app.textFields["email"].typeText("user@example.com")

    // Tap button
    app.buttons["Login"].tap()

    // Verify result
    XCTAssertTrue(app.staticTexts["Welcome"].exists)
}

Run UI tests:

bash

xcodebuild -workspace App.xcworkspace -scheme AppUITests \
  -destination "platform=iOS Simulator,id=$UDID" \
  test

如需实现点击、输入和UI元素查询功能，请使用XCUITest（苹果原生UI测试框架）。

相比基于MCP的自动化方案，该框架具备以下优势：

为iOS原生支持，始终保持更新
可完整访问无障碍元素树
可等待元素加载、处理动画
与Xcode测试运行器深度集成

完整操作模式请查看XCUITEST_GUIDE.md。

快速示例：

swift

// 在UI测试文件中
func testLogin() {
    let app = XCUIApplication()
    app.launch()

    // 在文本框中输入内容
    app.textFields["email"].tap()
    app.textFields["email"].typeText("user@example.com")

    // 点击按钮
    app.buttons["Login"].tap()

    // 验证结果
    XCTAssertTrue(app.staticTexts["Welcome"].exists)
}

运行UI测试：

bash

xcodebuild -workspace App.xcworkspace -scheme AppUITests \
  -destination "platform=iOS Simulator,id=$UDID" \
  test

Session Configuration

会话配置

Unlike MCP, CLI tools don't maintain session state. Use environment variables or a config file:

bash

undefined

与MCP不同，CLI工具不会维护会话状态。可通过环境变量或配置文件进行设置：

bash

undefined

Set up session variables

设置会话变量

export XCODE_WORKSPACE="/path/to/App.xcworkspace" export XCODE_SCHEME="App" export SIM_UDID="DD5E339B-468E-43C7-B219-54112C9D3250" export APP_BUNDLE_ID="com.your.app"

Use in commands

在命令中使用变量

xcodebuild -workspace "$XCODE_WORKSPACE" -scheme "$XCODE_SCHEME" ... xcrun simctl launch "$SIM_UDID" "$APP_BUNDLE_ID"

undefined

xcodebuild -workspace "$XCODE_WORKSPACE" -scheme "$XCODE_SCHEME" ... xcrun simctl launch "$SIM_UDID" "$APP_BUNDLE_ID"

undefined

Troubleshooting

故障排查

Build fails with "no matching destination"

构建失败，提示“no matching destination”

bash

undefined

bash

undefined

Check available destinations

查看可用目标设备

xcodebuild -workspace App.xcworkspace -scheme App -showDestinations

Use exact destination string from output

使用输出中的精确目标字符串

undefined

undefined

Simulator won't boot

模拟器无法启动

bash

undefined

bash

undefined

Check if already booted

检查是否已启动

xcrun simctl list devices | grep Booted

Force shutdown and reboot

强制关闭并重启

xcrun simctl shutdown $UDID xcrun simctl boot $UDID

undefined

xcrun simctl shutdown $UDID xcrun simctl boot $UDID

undefined

Can't find built .app

找不到构建好的.app文件

bash

undefined

bash

undefined

Check derived data path you specified

检查你指定的派生数据路径

ls -la /tmp/build/Build/Products/Debug-iphonesimulator/

Or use default derived data

或查看默认派生数据路径

ls ~/Library/Developer/Xcode/DerivedData/

undefined

ls ~/Library/Developer/Xcode/DerivedData/

undefined

Key Differences from XcodeBuildMCP

与XcodeBuildMCP的核心差异

Feature	XcodeBuildMCP	This Skill
Build	`build_sim({...})`	`xcodebuild -workspace ... build`
List sims	`list_sims()`	`xcrun simctl list devices`
Launch app	`launch_app_sim({...})`	`xcrun simctl launch $UDID $BUNDLE`
Screenshot	`screenshot({...})`	`xcrun simctl io $UDID screenshot`
Tap/Type	`tap({x,y})` , `type_text({...})`	XCUITest framework
Session state	Built-in	Environment variables

功能	XcodeBuildMCP	本方案
构建	`build_sim({...})`	`xcodebuild -workspace ... build`
列出模拟器	`list_sims()`	`xcrun simctl list devices`
启动应用	`launch_app_sim({...})`	`xcrun simctl launch $UDID $BUNDLE`
截图	`screenshot({...})`	`xcrun simctl io $UDID screenshot`
点击/输入	`tap({x,y})` , `type_text({...})`	XCUITest框架
会话状态	内置支持	环境变量管理

xcode-build

Original

Translation

Xcode Build Direct

Xcode 直接构建

When to Use This Skill

适用场景

Quick Start

快速开始

1. Discover Project Structure

1. 探查项目结构

List schemes in a workspace

列出工作区中的scheme

List schemes in a project

列出项目中的scheme

Show build settings

查看构建设置

2. Find Available Simulators

2. 查找可用模拟器

List all simulators

列出所有模拟器

List as JSON (better for parsing)

以JSON格式列出（更便于解析）

List only available simulators

仅列出可用模拟器

3. Build for Simulator

3. 为模拟器构建应用

Get simulator UUID first

先获取模拟器UUID

Build

执行构建

4. Install and Launch

4. 安装并启动应用

Find the built .app

查找构建好的.app文件

Install on simulator

在模拟器上安装应用

Launch app

启动应用

5. Take Screenshot

5. 截取屏幕截图

Detailed References

详细参考文档

Common Patterns

常用操作流程

Build + Run Workflow

构建+运行流程

1. Boot simulator

1. 启动模拟器

2. Build

2. 执行构建

3. Find and install app

3. 查找并安装应用

4. Launch with console output

4. 启动应用并输出控制台日志

Log Capture

日志捕获

Stream app logs (run in background)

流式输出应用日志（后台运行）

... interact with app ...

... 与应用进行交互 ...

Stop logging

停止日志捕获

Running Tests

运行测试

Unit tests

单元测试

Specific test class

指定测试类

UI Automation

UI自动化

Session Configuration

会话配置

Set up session variables

设置会话变量

Use in commands

在命令中使用变量

Troubleshooting

故障排查

Build fails with "no matching destination"