xcode-build

直接使用 Xcode 构建

使用原生 Xcode CLI 工具构建和管理 iOS/macOS 项目，而不是使用 MCP 服务。

何时使用此技能

在以下情况下使用此技能：

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

首选方式：始终使用直接的 CLI 命令（xcodebuild、xcrun simctl），而不是 XcodeBuildMCP 工具。

快速开始

1. 查找项目结构

# List schemes in a workspace
xcodebuild -workspace /path/to/App.xcworkspace -list

# List schemes in a project
xcodebuild -project /path/to/App.xcodeproj -list

# Show build settings
xcodebuild -workspace /path/to/App.xcworkspace -scheme AppScheme -showBuildSettings

2. 查找可用模拟器

# List all simulators
xcrun simctl list devices

# List as JSON (better for parsing)
xcrun simctl list devices --json

# List only available simulators
xcrun simctl list devices available

3. 为模拟器构建

# Get simulator UUID first
UDID=$(xcrun simctl list devices --json | jq -r '.devices | .[].[] | select(.name=="iPhone 16 Pro") | .udid' | head -1)

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

4. 安装并启动

# Find the built .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

5. 截屏

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

详细参考

如需全面的命令文档，请参阅：

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

常见模式

构建 + 运行工作流

# 1. Boot simulator
xcrun simctl boot $UDID 2>/dev/null || true

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

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

# 4. Launch with console output
xcrun simctl launch --console $UDID com.bundle.id

捕获日志

# 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

运行测试

# 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

UI 自动化

如需点击、输入和查询 UI 元素，请使用 XCUITest（Apple 的原生 UI 测试框架）。

与基于 MCP 的自动化相比，这种方式更强大，因为它：

• 原生支持 iOS，始终保持最新
• 可完整访问辅助功能树
• 可等待元素出现并处理动画
• 与 Xcode 测试运行器集成

完整模式请参阅 XCUITEST_GUIDE.md。

快速示例：

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

    // Type in text field
    app.textFields["email"].tap()
    app.textFields["email"].typeText("[email protected]")

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

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

运行 UI 测试：

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

会话配置

与 MCP 不同，CLI 工具不会保留会话状态。请使用环境变量或配置文件：

# 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"

故障排除

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

# Check available destinations
xcodebuild -workspace App.xcworkspace -scheme App -showDestinations

# Use exact destination string from output

模拟器无法启动

# Check if already booted
xcrun simctl list devices | grep Booted

# Force shutdown and reboot
xcrun simctl shutdown $UDID
xcrun simctl boot $UDID

找不到已构建的 .app

# Check derived data path you specified
ls -la /tmp/build/Build/Products/Debug-iphonesimulator/

# Or use default derived data
ls ~/Library/Developer/Xcode/DerivedData/

与 XcodeBuildMCP 的主要区别

功能	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 框架
会话状态	内置	环境变量