Back to Details

asc-builds-archive

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

asc Builds Archive & Export

asc 构建归档与导出

Archive Xcode projects, export IPA/PKG binaries, and optionally upload to App Store Connect — all in one command. See workflow.md for the full end-to-end flow.
一键完成Xcode项目归档、导出IPA/PKG二进制文件，还可选择上传至App Store Connect。完整端到端流程请查看workflow.md。

Commands

命令

Archive and export

归档并导出

bash
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
Workspace/project are auto-detected from the current directory if not specified. The command runs 
xcodebuild archive
followed by 
xcodebuild -exportArchive
with an auto-generated ExportOptions plist.
bash
asc builds archive \
  --scheme <SCHEME_NAME> \
  [--workspace MyApp.xcworkspace]     # 从当前目录自动检测
  [--project MyApp.xcodeproj]         # 从当前目录自动检测
  [--platform ios|macos|tvos|visionos] # 默认值：ios
  [--configuration Release]           # 默认值：Release
  [--export-method app-store-connect|ad-hoc|development|enterprise]  # 默认值：app-store-connect
  [--signing-style automatic|manual]  # 默认值：automatic
  [--team-id ABCD1234]               # 签名用的团队ID
  [--output-dir .build]              # 默认值：.build
若未指定工作区/项目，将从当前目录自动检测。该命令会先执行
xcodebuild archive
，再结合自动生成的ExportOptions plist执行
xcodebuild -exportArchive
。

Archive + export + upload (one command)

一步完成归档+导出+上传

bash
asc builds archive \
  --scheme <SCHEME_NAME> \
  --upload \
  --app-id <APP_ID> \
  --version 1.0.0 \
  --build-number 42
The 
--upload
flag chains the exported IPA/PKG directly into the existing 
asc builds upload
flow.
bash
asc builds archive \
  --scheme <SCHEME_NAME> \
  --upload \
  --app-id <APP_ID> \
  --version 1.0.0 \
  --build-number 42
--upload
参数会将导出的IPA/PKG直接接入已有的
asc builds upload
流程。

Resolve App ID

解析App ID

See project-context.md — check 
.asc/project.json
before asking the user or running 
asc apps list
.
请查看project-context.md — 在询问用户或执行
asc apps list
前，先检查
.asc/project.json
文件。

Typical Workflow

典型工作流

bash
APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')
bash
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'

若为空：询问用户或执行
asc apps list | jq -r '.data[0].id'

1. Archive, export, and upload in one command

1. 一键完成归档、导出与上传

asc builds archive --scheme MyApp --upload
--app-id "$APP_ID" --version 1.2.0 --build-number 55
asc builds archive --scheme MyApp --upload
--app-id "$APP_ID" --version 1.2.0 --build-number 55

2. Get the processed build ID

2. 获取已处理的构建ID

BUILD_ID=$(asc builds list --app-id $APP_ID | jq -r '.data[0].id')
BUILD_ID=$(asc builds list --app-id $APP_ID | jq -r '.data[0].id')

3. Distribute to TestFlight beta group

3. 分发至TestFlight测试组

asc builds add-beta-group --build-id $BUILD_ID --beta-group-id $GROUP_ID
asc builds add-beta-group --build-id $BUILD_ID --beta-group-id $GROUP_ID

4. Set TestFlight notes

4. 设置TestFlight测试说明

asc builds update-beta-notes --build-id $BUILD_ID --locale en-US --notes "New features"
asc builds update-beta-notes --build-id $BUILD_ID --locale en-US --notes "新功能"

5. Link to version and submit for review

5. 关联版本并提交审核

asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID asc versions submit --version-id $VERSION_ID
undefined
asc versions set-build --version-id $VERSION_ID --build-id $BUILD_ID asc versions submit --version-id $VERSION_ID
undefined

Archive only (no upload)

仅归档（不上传）

bash
undefined
bash
undefined

Archive and export to default .build/export/

归档并导出至默认目录.build/export/

asc builds archive --scheme MyApp
asc builds archive --scheme MyApp

The output includes an affordance for the next step:

输出内容包含下一步操作提示：

"upload": "asc builds upload --file .build/export/MyApp.ipa"

"upload": "asc builds upload --file .build/export/MyApp.ipa"

Ad-hoc distribution

临时分发（Ad-hoc）

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

Manual signing with team ID

手动签名并指定团队ID

asc builds archive --scheme MyApp --signing-style manual --team-id ABCD1234
asc builds archive --scheme MyApp --signing-style manual --team-id ABCD1234

macOS app

macOS应用

asc builds archive --scheme MyMacApp --platform macos
undefined
asc builds archive --scheme MyMacApp --platform macos
undefined

Export Methods

导出方式

MethodUse case
app-store-connect
App Store / TestFlight distribution (default)
ad-hoc
Direct distribution to registered devices
development
Development testing on registered devices
enterprise
In-house enterprise distribution
方式使用场景
app-store-connect
App Store / TestFlight分发（默认）
ad-hoc
直接分发给已注册设备
development
已注册设备上的开发测试
enterprise
企业内部分发

Signing Options

签名选项

FlagDefaultDescription
--signing-style
automatic
automatic
lets Xcode manage profiles; 
manual
requires pre-configured profiles
--team-id
(none)Apple Developer team ID; useful when multiple teams are configured
When 
--signing-style automatic
(the default), the export step passes 
-allowProvisioningUpdates
to 
xcodebuild
so profiles are automatically resolved.
参数默认值说明
--signing-style
automatic
automatic
由Xcode管理配置文件；
manual
需要预先配置好的配置文件
--team-id
（无）Apple开发者团队ID；当配置了多个团队时非常有用
当使用默认的
--signing-style automatic
时，导出步骤会向
xcodebuild
传递
-allowProvisioningUpdates
参数，自动解析配置文件。

CAEOAS Affordances

CAEOAS 操作提示

Archive-only responses include an 
upload
affordance pointing to the exported binary:
json
{
  "data": [{
    "ipaPath": ".build/export/MyApp.ipa",
    "exportPath": ".build/export",
    "affordances": {
      "upload": "asc builds upload --file .build/export/MyApp.ipa"
    }
  }]
}
When 
--upload
is used, the response matches the standard build upload format with 
checkStatus
and 
listBuilds
affordances.
仅归档的响应会包含指向导出二进制文件的
upload
操作提示：
json
{
  "data": [{
    "ipaPath": ".build/export/MyApp.ipa",
    "exportPath": ".build/export",
    "affordances": {
      "upload": "asc builds upload --file .build/export/MyApp.ipa"
    }
  }]
}
当使用
--upload
参数时，响应会匹配标准的构建上传格式，包含
checkStatus
和
listBuilds
操作提示。

Troubleshooting

故障排查

ErrorCauseFix
"Unknown platform: watchos"Invalid platform argumentUse: 
ios
, 
macos
, 
tvos
, 
visionos
"Scheme not found"Scheme doesn't exist or workspace not detectedPass 
--workspace
or 
--project
explicitly
"no signing identity found"Code signing not configuredConfigure signing in Xcode or pass 
--export-method development
"No profiles for 'X' were found"Provisioning profile not availableDefault 
--signing-style automatic
resolves this; or pass 
--team-id
explicitly
"app-store" is deprecatedOld export method nameUse 
app-store-connect
(now the default)
"No .ipa or .pkg found"Export succeeded but no binary producedCheck xcodebuild output, verify scheme builds an app target
"--app-id is required"
--upload
used without 
--app-id
Provide 
--app-id
or run 
asc init
first
错误原因解决方法
"Unknown platform: watchos"无效的平台参数使用：
ios
, 
macos
, 
tvos
, 
visionos
"Scheme not found"Scheme不存在或未检测到工作区显式传递
--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输出，验证Scheme是否构建应用目标
"--app-id is required"使用
--upload
但未提供
--app-id
提供
--app-id
或先执行
asc init

Reference

参考文档

See workflow.md for:
  • Auto-detection logic for workspace/project
  • ExportOptions plist generation details
  • Platform-to-destination mapping
  • How archive chains into the upload flow
请查看workflow.md了解：
  • 工作区/项目的自动检测逻辑
  • ExportOptions plist的生成细节
  • 平台与目标的映射关系
  • 归档流程如何衔接至上传流程