asc-xcode-build

Xcode 构建与导出

需要从源代码构建应用并为 App Store Connect 做好准备时，请使用此技能。如果项目适用，请优先使用 asc xcode archive 和 asc xcode export，而不是直接采用 xcodebuild 配方。

前提条件

如果在 Linux 上使用已准备好的 xtool 软件包，请改用便携式 iOS 构建， 而不是下面的 Xcode 命令。该工作流对项目和签名的要求范围更窄。

• 已安装 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。

版本命令会读取项目和 xcconfig 设置，而不会启动 Xcode。如果这些设置无法解析版本值，默认的 --xcodebuild-settings-lookup auto 会回退到 xcodebuild -showBuildSettings，并向 stderr 输出警告。在不得隐式启动 Xcode 的自动化中，请使用 --xcodebuild-settings-lookup never。

不进行归档的编译

普通的模拟器、设备或 CI 验证构建，请使用 asc xcode build。必须提供且仅提供一个项目或工作区，以及一个 scheme。

asc xcode build \
  --project "App.xcodeproj" \
  --scheme "App" \
  --destination "platform=iOS Simulator,name=iPhone 17 Pro Max,OS=27.0" \
  --no-code-signing \
  --result-bundle-path ".asc/artifacts/App.xcresult" \
  --output json

如果省略 --derived-data-path，asc 会使用源代码检出目录之外的稳定缓存。结果包的目标路径必须尚不存在。Xcode 日志输出到 stderr，结构化结果输出到 stdout。

推荐的 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。

要生成可安装到已注册设备上的 IPA，请使用 Xcode 当前的 release-testing 方法。旧的 ad-hoc 写法已被 Xcode 弃用， 且 asc 不接受此写法：

asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --method release-testing \
  --signing-style manual \
  --team-id "TEAM_ID" \
  --output json

需要审核或重复使用时，请单独生成 release-testing plist：

asc xcode export-options generate \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --method release-testing \
  --signing-style manual \
  --team-id "TEAM_ID" \
  --output-path ".asc/ExportOptions.release-testing.plist" \
  --output json

release-testing 始终在本地导出，且不能与 --wait 一起使用。显式指定的 --export-options plist 不能与 --method、--signing-style 或 --team-id 一起使用。若要进行设备与描述文件协调、隔离签名、私有发布、断点续传和实时验证，请改用 asc-ad-hoc-distribution 技能，而不是手动组合这些阶段。

要通过 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，请使用辅助工具导出，然后上传安装包：

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

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

对于 .pkg 上传，必须提供 --version 和 --build-number，因为不会像 IPA 元数据那样自动提取这些信息。如果项目需要自定义导出配置，请添加 --export-options "ExportOptions.plist"。

原始 xcodebuild 回退方案

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

xcodebuild -showBuildSettings -scheme "App"

故障排除

导出时找不到对应 Bundle ID 的描述文件

• 在 asc xcode export 中添加 --xcodebuild-flag=-allowProvisioningUpdates。
• 确认已在 Xcode 中登录 Apple ID。
• 使用 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 生成确定性的本地产物。
• 默认生成的导出方法仍为 app-store-connect；对于已注册设备安装，请明确指定 --method release-testing。
• 仅在有意替换现有本地产物时使用 --overwrite。
• 如果下一步依赖已处理的构建，请在上传/发布流程中使用 --wait。
• 如需确认提交是否就绪，请使用 asc-submission-health。