ios-build

iOS project compilation

Via xcodebuild command line to compile an iOS project, suitable for local builds, scripts, and CI/CD.

Project type

Type	How to open	Description
Pure Xcode project	`.xcodeproj`	No CocoaPods
CocoaPods project	`.xcworkspace`	Has a Podfile,must use workspace

Basic commands

# 进入工程目录（.xcodeproj 或 .xcworkspace 所在目录）
cd /path/to/YourProject

# 使用 .xcworkspace（CocoaPods 工程）
xcodebuild -workspace YourProject.xcworkspace -scheme YourScheme -destination 'generic/platform=iOS' build

Using .xcodeproj (pure project)

xcodebuild -project YourProject.xcodeproj -scheme YourScheme -destination 'generic/platform=iOS' build


## 常用 destination

| destination | 说明 |
|-------------|------|
| `generic/platform=iOS` | 通用 iOS 设备（不指定具体设备） |
| `generic/platform=iOS Simulator` | 任意模拟器 |
| `platform=iOS Simulator,name=iPhone 15` | 指定模拟器 |
| `platform=iOS,id=<UDID>` | 指定真机 |

## 查看 scheme

```bash
xcodebuild -list -workspace YourProject.xcworkspace
# 或
xcodebuild -list -project YourProject.xcodeproj

In the output, Schemes: lists the available schemes, usually consistent with the target name.

Common operations

# 清理后构建
xcodebuild clean build -workspace YourProject.xcworkspace -scheme YourScheme -destination 'generic/platform=iOS'

# 指定配置（Debug/Release）
xcodebuild -configuration Release -workspace YourProject.xcworkspace -scheme YourScheme -destination 'generic/platform=iOS' build

# 归档（用于分发）
xcodebuild archive -workspace YourProject.xcworkspace -scheme YourScheme -archivePath ./build/App.xcarchive -destination 'generic/platform=iOS'

Common issues

Scheme not found: use -list to check, or check whether the scheme is shared (Edit Scheme → check Shared)
CocoaPods project: must use -workspace, cannot use -project
Sandbox restrictions: if DerivedData has no write permission in CI/scripts, you can add -derivedDataPath ./DerivedData to specify a writable directory
Simulator service abnormal：generic/platform=iOS does not depend on the simulator, suitable for GUI-less environments

More references

For full parameters, exporting IPA, etc., see reference.md