asc-xcode-build

Xcode 构建与导出

当你需要从源代码构建应用并准备上传到 App Store Connect 时，使用此技能。在适合项目的情况下，优先使用 asc xcode archive 和 asc xcode export，而不是原始的 xcodebuild 配方。

前置条件

• 已安装 Xcode 和命令行工具。
• 签名身份和配置文件可用，或已启用自动签名。
• 当需要上传或构建查询时，已配置 App Store Connect 认证。

管理版本和构建号

asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version edit --next-build-number --app "APP_ID" --platform IOS
asc xcode version bump --type build
asc xcode version bump --type patch
asc xcode version bump --type build --next-build-number --app "APP_ID" --platform IOS

当不在项目根目录运行时，使用 --project-dir "./MyApp"。当目录包含多个项目时，使用 --project "./MyApp/App.xcodeproj"。在多目标或多配置项目中，使用 --target "App" 和 --configuration "Release" 进行确定性读写。

为避免构建号过低被拒绝，可通过一条命令解析并应用远程安全的构建号：

asc xcode version edit --next-build-number --app "APP_ID" --platform IOS --output json

版本修改会在写入前验证完整变更，并返回结构化输出，标识更改的配置和文件。编辑器会递归处理 xcconfig 包含，并保留不相关的项目和 xcconfig 内容。如果只想检查远程安全值而不修改项目，请单独使用 asc builds next-build-number。

推荐的 iOS/tvOS/visionOS 构建流程

1. 使用 asc 归档

asc xcode archive \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=iOS \
  --output json

对于仅项目应用，使用 --project "App.xcodeproj" 代替 --workspace。

2. 使用 asc 导出

默认情况下，asc xcode export 会生成使用自动签名的 App Store Connect 导出选项。它使用本地导出目标，除非设置了 --wait，此时使用直接上传：

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --output json

当需要审查、重用或手动签名时，单独生成 plist：

asc xcode export-options generate \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --output-path ".asc/ExportOptions.plist" \
  --output json

对于手动签名，添加 --signing-style manual 并可选择 --team-id "TEAM_ID"。现有文件需要 --overwrite。

要通过 Xcode 直接上传并等待 App Store Connect 处理，省略 --export-options 并添加 --wait：

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --wait \
  --output json

3. 上传或发布

上传导出的 IPA：

asc builds upload --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --wait

分发到 TestFlight：

asc publish testflight --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --group "GROUP_ID" --wait

发布到 App Store：

asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait
asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait --submit --confirm

macOS App Store 流程

使用辅助工具归档：

asc xcode archive \
  --project "MacApp.xcodeproj" \
  --scheme "MacApp" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/MacApp.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=macOS \
  --output json

如果你的 macOS 导出生成 .pkg，请使用 Xcode 导出和你的 ExportOptions.plist，然后上传包：

xcodebuild -exportArchive \
  -archivePath ".asc/artifacts/MacApp.xcarchive" \
  -exportPath ".asc/artifacts/MacAppExport" \
  -exportOptionsPlist "ExportOptions.plist" \
  -allowProvisioningUpdates

asc builds upload \
  --app "APP_ID" \
  --pkg ".asc/artifacts/MacAppExport/MacApp.pkg" \
  --version "1.0.0" \
  --build-number "123" \
  --wait

对于 .pkg 上传，--version 和 --build-number 是必需的，因为它们不像 IPA 元数据那样自动提取。

原始 xcodebuild 回退

仅当 asc xcode archive --help 或 asc xcode export --help 未涵盖项目特定选项时，才使用原始 xcodebuild。优先通过 --xcodebuild-flag 传递额外参数。

xcodebuild -showBuildSettings -scheme "App"

故障排除

导出时没有 bundle ID 的配置文件

• 在 asc xcode export 中添加 --xcodebuild-flag=-allowProvisioningUpdates。
• 确认 Apple ID 已登录 Xcode。
• 使用 asc-signing-setup 技能验证配置文件。

CFBundleVersion 过低

asc xcode version edit --next-build-number --app "APP_ID" --platform IOS

然后重新构建并上传。

构建因缺少 macOS 图标被拒绝

macOS 需要包含所有必需尺寸的 ICNS 图标。修复资源目录，重新构建，然后再次导出/上传。

注意事项

• 优先使用 asc xcode archive 和 asc xcode export 以获得确定性的本地产物。
• 仅在有意替换现有本地产物时使用 --overwrite。
• 当下一步依赖于已处理的构建时，在上传/发布路径中使用 --wait。
• 关于提交准备情况，请使用 asc-submission-health。