下面我将从基础到高级，详细讲解 xcodebuild 的打包命令。

核心命令结构

最常用的打包命令结构如下：

xcodebuild -project <YourProjectName>.xcodeproj \
           -scheme <YourSchemeName> \
           -configuration <YourConfiguration> \
           -destination generic/platform=iOS \
           archive \
           -archivePath <PathToYourArchive>.xcarchive \
           -allowProvisioningUpdates \
           -allowProvisioningDeviceRegistration

我们分解这个命令中的每一个部分。

基础命令参数

这些是构建和打包所必需的核心参数。

打包成 IPA 文件

仅仅执行 archive 命令只会生成 .xcarchive 文件，这个文件不能直接安装，你需要再执行一个 exportArchive 动作来将其导出为 .ipa 文件。

完整的两步流程命令如下：

# 1. 归档
xcodebuild -project MyApp.xcodeproj \
           -scheme MyApp \
           -configuration Release \
           -destination generic/platform=iOS \
           archive \
           -archivePath ./build/MyApp.xcarchive \
           -allowProvisioningUpdates \
           -allowProvisioningDeviceRegistration
# 2. 导出为 IPA
xcodebuild -exportArchive \
           -archivePath ./build/MyApp.xcarchive \
           -exportPath ./build/ \
           -exportOptionsPlist ./ExportOptions.plist \
           -allowProvisioningUpdates

exportArchive 动作的关键参数：

ExportOptions.plist 文件详解

ExportOptions.plist 是控制导出类型和方式的核心文件,你必须创建它。

示例 1：导出为 App Store 上传包

<!-- ExportOptions-AppStore.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>uploadSymbols</key>
    <true/>
    <key>uploadBitcode</key>
    <false/>
</dict>
</plist>

示例 2：导出为 Ad Hoc 分发包

<!-- ExportOptions-AdHoc.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>ad-hoc</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.yourcompany.yourappbundleid</key>
        <string>Provisioning Profile Name for AdHoc</string>
    </dict>
    <key>signingCertificate</key>
    <string>iPhone Distribution</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
    <key>destination</key>
    <array>
        <string>export</string>
    </array>
</dict>
</plist>

完整实战脚本示例

这是一个完整的 Bash 脚本，它会清理、构建、归档并导出 IPA 文件。

#!/bin/bash
# --- 设置变量 ---
PROJECT_NAME="MyApp.xcodeproj"
SCHEME_NAME="MyApp"
CONFIGURATION="Release"
PLATFORM="iOS"
ARCHIVE_PATH="./build/${SCHEME_NAME}.xcarchive"
IPA_PATH="./build/${SCHEME_NAME}.ipa"
EXPORT_OPTIONS_PLIST="./ExportOptions-AppStore.plist"
# --- 创建构建目录 ---
mkdir -p ./build
echo "🚀 开始构建..."
# --- 1. 清理项目 (可选) ---
echo "🧹 清理项目..."
xcodebuild -project ${PROJECT_NAME} \
           -scheme ${SCHEME_NAME} \
           -configuration ${CONFIGURATION} \
           clean
# --- 2. 归档项目 ---
echo "📦 归档项目..."
xcodebuild -project ${PROJECT_NAME} \
           -scheme ${SCHEME_NAME} \
           -configuration ${CONFIGURATION} \
           -destination "generic/platform=${PLATFORM}" \
           archive \
           -archivePath ${ARCHIVE_PATH} \
           -allowProvisioningUpdates \
           -allowProvisioningDeviceRegistration
# 检查归档是否成功
if [ $? -ne 0 ]; then
    echo "❌ 归档失败！"
    exit 1
fi
echo "✅ 归档成功！"
# --- 3. 导出 IPA ---
echo "📤 导出 IPA..."
xcodebuild -exportArchive \
           -archivePath ${ARCHIVE_PATH} \
           -exportPath $(dirname ${IPA_PATH}) \
           -exportOptionsPlist ${EXPORT_OPTIONS_PLIST} \
           -allowProvisioningUpdates
# 检查导出是否成功
if [ $? -ne 0 ]; then
    echo "❌ 导出 IPA 失败！"
    exit 1
fi
echo "✅ IPA 导出成功！"
echo "📁 IPA 文件位置: ${IPA_PATH}"
# --- 4. 删除归档文件 (可选) ---
# rm -rf ${ARCHIVE_PATH}
echo "🎉 所有任务完成！"

如何使用这个脚本：

1. 将上述代码保存为 build.sh 文件。
2. 确保你的 ExportOptions-AppStore.plist 文件在项目根目录下。
3. 给脚本添加可执行权限：chmod +x build.sh
4. 在终端中运行：./build.sh

常见问题与技巧

• 找不到 Scheme 或 Project

  • 使用 xcodebuild -list 命令可以列出当前 Xcode 项目中所有的 Scheme 和目标。

    xcodebuild -list -project MyApp.xcodeproj

• 签名错误

  • 确保你的 Keychain 中有有效的开发者证书和描述文件。
  • -allowProvisioningUpdates 和 -allowProvisioningDeviceRegistration 参数非常有用，它们会在打包过程中自动更新或创建 Provisioning Profile,避免很多手动操作的麻烦。

• 自动化构建

  在 CI/CD 工具（如 Jenkins, GitLab CI, GitHub Actions）中，通常会将上述脚本放入，并配置好环境变量（如证书密码、Team ID 等）来实现全自动的构建和打包。

• 仅编译不打包

  • 如果只是想检查代码是否能编译，可以使用 build 动作代替 archive。

    xcodebuild -project MyApp.xcodeproj -scheme MyApp build

• 使用 .xcworkspace (CocoaPods)

  • 如果你的项目使用 CocoaPods，通常会有一个 .xcworkspace 文件，在这种情况下，你需要使用 -workspace 参数而不是 -project。

    xcodebuild -workspace MyApp.xcworkspace \
           -scheme MyApp \
           -configuration Release \
           archive \
           -archivePath ./build/MyApp.xcarchive

希望这份详细的指南能帮助你熟练掌握 Xcode 的命令行打包！