app-store-connect-cli-skills 是一个配合 asc cli 使用的开源技能包，其中的 asc-xcode-build 技能覆盖"从 Archive、ExportOptions 到上传"的完整构建流程，帮你把 Xcode 项目打包成可上传 App Store Connect 的 IPA 或 macOS PKG。本文按 5 个步骤带你走通这条流水线，并附上常见报错的快速修复方法。

为什么选择 asc xcode-build？

平时手动构建要记一堆xcodebuild参数、手写ExportOptions.plist、还要担心构建号被 Apple 拒收。asc-xcode-build 技能把这些步骤封装成确定性命令：

• 自动生成 App Store Connect 导出配置，支持自动签名与手动签名
• 通过--next-build-number一次解决"CFBundleVersion 太低"的拒收问题
• 结构化 JSON 输出，方便接入 CI/CD 与 Agent 自动化
• 同一套流程覆盖 iOS 的 IPA 和 macOS 的 PKG

技能的完整说明见 skills/asc-xcode-build/SKILL.md，项目概览见 README.md。

安装与启用技能

先安装 asc cli，再一条命令安装全部技能：

asc install-skills

也可以在本地克隆技能包后自行查看每个技能的定义：

git clone https://gitcode.com/gh_mirrors/ap/app-store-connect-cli-skills

安装完成后，当 Agent 检测到构建相关任务时会自动启用对应技能。

前置检查清单

开工前确认三件事（原文见 前置条件章节）：

1. ✅ 已安装 Xcode 与 Command Line Tools
2. ✅ 签名身份与描述文件可用，或已启用自动签名
3. ✅ 需要上传时已配置 App Store Connect 认证（asc auth login或ASC_*环境变量）

签名证书和描述文件如果缺失，可先用 asc-signing-setup 技能 创建 Bundle ID、证书与 Profile。

第一步：固定版本与构建号

构建号太低是上传被拒最常见的原因。建议构建前先查看并远程安全地递增构建号：

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

--next-build-number会读取 App Store Connect 上已有的最大构建号，一次命令同时完成解析与写入，避免"本地改了、上传还是被拒"的来回折腾。多 target / 多 configuration 的项目可加--project-dir、--target、--configuration精确定位，细节见 版本管理章节。

第二步：Archive 归档项目

用asc xcode archive替代裸xcodebuild，产物默认落在.asc/artifacts/目录，便于后续步骤复用：

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

两个小贴士：

• 纯.xcodeproj项目把--workspace换成--project即可
• 项目特有的 xcodebuild 参数优先通过--xcodebuild-flag透传，而不是退回裸命令

完整示例见 Archive 章节。

第三步：生成 ExportOptions.plist

asc xcode export默认会生成 App Store Connect 导出配置并启用自动签名，无需手动写 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 现行的--method release-testing（旧写法ad-hoc已被 Xcode 弃用，asc 也不再接受）

参数组合与限制说明见 导出配置章节。

第四步：Export 导出 IPA（或 PKG）

拿到 archive 后一条命令导出：

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

• 加--wait可让 asc 直接通过 Xcode 上传并等待 App Store Connect 处理完成
• release-testing方式只支持本地导出，不能与--wait组合使用
• 显式传入--export-optionsplist 时，就不能再叠加--method、--signing-style或--team-id

导出与直传的参数细节见 Export 章节。

第五步：上传与分发

导出完成后，按分发目标选择命令：

# 仅上传构建 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

当后续步骤依赖"构建已处理完成"时（比如紧接着提审），记得带上--wait。上传与发布的完整用法见 上传章节。

macOS 应用：PKG 专属流程

macOS 走同一套 archive → export，只是导出参数换成--pkg-path：

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"。完整 macOS 流程见 macOS App Store 流程章节。

常见报错与快速修复

逐项排查思路见 Troubleshooting 章节；描述文件层面的问题可交给 asc-signing-setup 技能 处理。

最佳实践与延伸阅读

• 🎯 优先用asc xcode archive/asc xcode export获得确定性本地产物，仅在两者都不覆盖时才退回裸xcodebuild（参考 Raw fallback 章节）
• --overwrite只用于你确实要替换本地产物的场景
• Linux 上没有 Xcode？可用 portable-ios.md 描述的asc builds compile/asc builds package便携编译链路，但其项目与签名约束更窄
• 构建上传只是开始：元数据暂存、提审与发布编排见 asc-release-flow 技能，提审卡点诊断见 skills 目录中的 asc-submission-health

按这套流程走完，从源码到 App Store Connect 的 IPA / PKG 构建就变成了一连串可重复、可审计的 asc 命令——这正是 app-store-connect-cli-skills 想要带给你的确定性。