xcodebuild

在命令行构建、测试和归档 Xcode 工程，适用于 CI 和自动化。

补充说明

xcodebuild 是完整 Xcode 提供的构建工具，能读取 .xcodeproj 或 .xcworkspace，按 scheme、configuration 和 destination 执行 build、test、archive。只有一个 CLT 时会直接报 tool 'xcodebuild' requires Xcode, but active developer directory ... is a command line tools instance，必须安装完整 Xcode 并用 xcode-select --switch 指过去。

工程有 CocoaPods 或 Swift Package 依赖时通常用 .xcworkspace，纯 Xcode 工程才用 .xcodeproj。-scheme 必须存在且被共享，否则本地能看到、CI 却报 scheme 找不到。-destination 要写精确的平台和名称，模拟器名称可先用 xcrun simctl list devices available 确认。

构建产物默认写入 DerivedData，CI 上建议用 -derivedDataPath 固定到工作目录，便于缓存和清理。签名问题在 CI 上最常见：模拟器构建可以 CODE_SIGNING_ALLOWED=NO，真机或归档则需要有效的证书和描述文件，必要时加 -allowProvisioningUpdates 让 Xcode 自动处理。

常用示例

# 查看 Xcode 版本和可用 SDK
% xcodebuild -version
% xcodebuild -showsdks

# 列出 workspace 里的 scheme、target 和 configuration
% xcodebuild -list -workspace App.xcworkspace

# 构建模拟器版本
% xcodebuild -workspace App.xcworkspace -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 15' build

# 运行测试
% xcodebuild test -workspace App.xcworkspace -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 15'

# 查看构建设置，确认 bundle id 和签名配置
% xcodebuild -showBuildSettings -scheme App | grep PRODUCT_BUNDLE_IDENTIFIER

# 固定 DerivedData，便于 CI 缓存和清理
% xcodebuild -workspace App.xcworkspace -scheme App \
  -destination 'generic/platform=iOS' -derivedDataPath build/DerivedData build

# 归档并导出 ipa
% xcodebuild archive -workspace App.xcworkspace -scheme App \
  -archivePath build/App.xcarchive -destination 'generic/platform=iOS'
% xcodebuild -exportArchive -archivePath build/App.xcarchive \
  -exportOptionsPlist ExportOptions.plist -exportPath build/export

# 模拟器构建关闭签名，避免 CI 缺证书
% xcodebuild -workspace App.xcworkspace -scheme App \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  CODE_SIGNING_ALLOWED=NO build

易错点与排错

• 报 requires Xcode：当前是 CLT，安装完整 Xcode 并 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer。
• 报 does not contain an Xcode project：工作目录或 -workspace/-project 路径不对；先 ls 确认文件存在。
• scheme not found：scheme 未共享，或用了 .xcodeproj 而依赖需要 .xcworkspace；在 Xcode 的 Manage Schemes 勾选 Shared。
• destination 不匹配：设备名、系统版本或平台写错；用 xcrun simctl list devices available 查可用模拟器，归档用 generic/platform=iOS。
• 签名失败 No profiles for ... were found：CI 未安装证书/描述文件；配置签名环境，或仅模拟器构建时关闭签名。
• DerivedData 缓存导致旧代码或旧资源：用 -derivedDataPath 固定路径并在 CI 清理，必要时先 xcodebuild clean。
• 许可证或首次启动组件未完成：sudo xcodebuild -license accept 和 sudo xcodebuild -runFirstLaunch。
• 只看 -quiet 的输出可能漏掉关键警告；失败时去掉 -quiet，并检查退出码和 ** BUILD FAILED **。

相关命令

• xcrun — 定位 clang、simctl、notarytool 等工具
• xcode-select — 切换 xcodebuild 使用的 Xcode
• codesign — 检查签名和 entitlements
• brew — 安装构建脚本依赖

参考链接

• Xcode — Apple Developer
• Apple: Xcode command-line tool reference

读完自测

合上页面，先回答，再展开对照。

1. 为什么装了 Command Line Tools 仍然不能运行 xcodebuild？
2. CI 上 scheme 找不到，常见原因是什么？
3. 模拟器构建时怎样避免签名失败？