asc-builds-archive

asc 构建归档与导出

归档 Xcode 项目、导出 IPA/PKG 二进制文件，并可选择上传到 App Store Connect——一条命令即可完成。完整端到端流程请参阅 workflow.md。

命令

归档并导出

asc builds archive \
  --scheme <SCHEME_NAME> \
  [--workspace MyApp.xcworkspace]     # auto-detected from cwd
  [--project MyApp.xcodeproj]         # auto-detected from cwd
  [--platform ios|macos|tvos|visionos] # default: ios
  [--configuration Release]           # default: Release
  [--export-method app-store-connect|ad-hoc|development|enterprise]  # default: app-store-connect
  [--signing-style automatic|manual]  # default: automatic
  [--team-id ABCD1234]               # team ID for signing
  [--output-dir .build]              # default: .build

如果未指定工作区/项目，系统会从当前目录自动检测。该命令先运行 xcodebuild archive，再运行 xcodebuild -exportArchive，并自动生成 ExportOptions plist。

归档 + 导出 + 上传（一条命令）

# Get the next build number automatically
BUILD_NUMBER=$(asc builds next-number --app-id <APP_ID> --version 1.0.0 --platform ios)

asc builds archive \
  --scheme <SCHEME_NAME> \
  --upload \
  --app-id <APP_ID> \
  --version 1.0.0 \
  --build-number "$BUILD_NUMBER"

--upload 标志会将导出的 IPA/PKG 直接接入现有的 asc builds upload 流程。

解析 App ID

请参阅 project-context.md——在询问用户或运行 asc apps list 前，先检查 .asc/project.json。

典型工作流

APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')
# If empty: ask user or run `asc apps list | jq -r '.data[0].id'`

# 1. Get the next build number
BUILD_NUMBER=$(asc builds next-number --app-id "$APP_ID" --version 1.2.0 --platform ios)

# 2. Archive, export, and upload in one command
asc builds archive --scheme MyApp --upload \
  --app-id "$APP_ID" --version 1.2.0 --build-number "$BUILD_NUMBER"

# 3. Get the processed build ID
BUILD_ID=$(asc builds list --app-id $APP_ID | jq -r '.data[0].id')

# 4. Distribute to TestFlight beta group
asc builds add-beta-group --build-id $BUILD_ID --beta-group-id $GROUP_ID

# 5. Set TestFlight notes
asc builds update-beta-notes --build-id $BUILD_ID --locale en-US --notes "New features"

# 6. Link to version and submit for review
asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID
asc versions submit --version-id $VERSION_ID

仅归档（不上传）

# Archive and export to default .build/export/
asc builds archive --scheme MyApp

# The output includes an affordance for the next step:
# "upload": "asc builds upload --file .build/export/MyApp.ipa"

# Ad-hoc distribution
asc builds archive --scheme MyApp --export-method ad-hoc --output-dir dist/

# Manual signing with team ID
asc builds archive --scheme MyApp --signing-style manual --team-id ABCD1234

# macOS app
asc builds archive --scheme MyMacApp --platform macos

导出方式

方式	用途
app-store-connect	App Store / TestFlight 分发（默认）
ad-hoc	直接分发到已注册的设备
development	在已注册的设备上进行开发测试
enterprise	企业内部使用的分发方式

签名选项

标志	默认值	描述
--signing-style	automatic	automatic 由 Xcode 管理配置文件；manual 需要预先配置配置文件
--team-id	（无）	Apple Developer 团队 ID；配置了多个团队时很有用

使用 --signing-style automatic（默认值）时，导出步骤会向 xcodebuild 传递 -allowProvisioningUpdates，以自动解析配置文件。

CAEOAS 功能

仅归档的响应包含一个指向已导出二进制文件的 upload 功能入口：

{
  "data": [{
    "ipaPath": ".build/export/MyApp.ipa",
    "exportPath": ".build/export",
    "affordances": {
      "upload": "asc builds upload --file .build/export/MyApp.ipa"
    }
  }]
}

使用 --upload 时，响应格式与标准构建上传格式一致，其中包含 checkStatus 和 listBuilds 功能入口。

故障排查

错误	原因	解决方法
"Unknown platform: watchos"	平台参数无效	请使用：ios、macos、tvos、visionos
"Scheme not found"	方案不存在或未检测到工作区	显式传入 --workspace 或 --project
"no signing identity found"	未配置代码签名	在 Xcode 中配置签名，或传入 --export-method development
"No profiles for 'X' were found"	找不到配置文件	默认的 --signing-style automatic 会自动解析；也可显式传入 --team-id
"app-store" is deprecated	使用了旧的导出方式名称	请使用 app-store-connect（现为默认值）
"No .ipa or .pkg found"	导出成功，但未生成二进制文件	检查 xcodebuild 输出，并确认方案会构建应用目标
"--app-id is required"	使用了 --upload，但未传入 --app-id	提供 --app-id，或先运行 asc init

参考

请参阅 workflow.md，了解：

• 工作区/项目的自动检测逻辑
• ExportOptions plist 的生成详情
• 平台到目标位置的映射
• 归档如何接入上传流程