SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场asc-builds-archive

asc-builds-archive

编程与开发

查看项目

更新于 10-16 04:14

技能介绍

用途

asc-builds-archive 用于归档 Xcode 项目、导出 IPA/PKG 二进制文件，并可选上传到 App Store Connect，全部通过一条命令完成。需要归档 Xcode 项目、导出二进制、上传构建等场景时可以使用该技能。

主要命令

归档与导出

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 时会从当前目录自动检测。命令先运行 xcodebuild archive，再用自动生成的 ExportOptions plist 运行 xcodebuild -exportArchive。

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

# 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

先检查 .asc/project.json，然后再询问用户或运行 asc apps list。

典型工作流

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

导出方式

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

签名选项

Flag Default Description
--signing-style automatic automatic 由 Xcode 管理描述文件；manual 需要预先配置好的描述文件
--team-id (none) Apple Developer 团队 ID；配置了多个团队时有用

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

CAEOAS Affordances

仅归档的响应会包含指向导出二进制的上传 affordance：

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

使用 --upload 时，响应与标准构建上传格式一致，包含 checkStatus 和 listBuilds affordances。

故障排查

Error Cause Fix
"Unknown platform: watchos" 平台参数无效 使用：ios、macos、tvos、visionos
"Scheme not found" scheme 不存在或未检测到 workspace 显式传入 --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 target
"--app-id is required" 使用 --upload 但未提供 --app-id 提供 --app-id 或先运行 asc init

参考

workflow.md 中包含：

  • workspace/project 的自动检测逻辑
  • ExportOptions plist 生成细节
  • 平台到 destination 的映射
  • archive 如何接入 upload 流程

适用场景

iOS、macOS、tvOS、visionOS 应用的归档、导出与发布流程，包括 App Store 与 TestFlight 分发、ad-hoc 分发、开发测试、企业内部分发，以及归档后接着完成 TestFlight 分发、版本关联与提交审核的完整工作流。

限制

除资料中已给出的命令、参数、默认值、导出方式、签名选项与故障排查信息外，其余关于收费、价格、平台支持范围、实际效果等事实暂未提供。