ios-build

name	ios-build
description	Compiles iOS Xcode projects via xcodebuild. Use when building iOS apps, running xcodebuild, compiling Xcode projects, CI/CD for iOS, or when the user mentions iOS 编译、构建、build.

iOS 工程编译

通过 xcodebuild 命令行编译 iOS 工程，适用于本地构建、脚本、CI/CD。

工程类型

类型	打开方式	说明
纯 Xcode 工程	.xcodeproj	无 CocoaPods
CocoaPods 工程	.xcworkspace	有 Podfile，必须用 workspace

基本命令

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

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

# 使用 .xcodeproj（纯工程）
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

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

输出中的 Schemes: 下列出可用 scheme，通常与 target 名一致。

常用操作

# 清理后构建
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'

常见问题

• 找不到 scheme：用 -list 查看，或检查 scheme 是否 shared（Edit Scheme → 勾选 Shared）
• CocoaPods 工程：必须用 -workspace，不能用 -project
• 沙盒限制：CI/脚本中若 DerivedData 无写权限，可加 -derivedDataPath ./DerivedData 指定可写目录
• 模拟器服务异常：generic/platform=iOS 不依赖模拟器，适合无 GUI 环境

更多参考

• 完整参数、导出 IPA 等见 reference.md