App Store Connect CLI：命令行跑通 iOS 上架流程

App Store Connect CLI 把 App Store Connect API 的构建上传、TestFlight、提交审核、签名、订阅价格和分析查询收成 asc 子命令，用 Go 编写，可接入 CI/CD 流程。这篇文章梳理它的主要功能、安装与认证方式、关键参数，以及真实 Issue 反映出的问题，并和同类项目做横向对照，帮你判断是否值得引入到现有的发布链路里。

App Store Connect 的后台是一套网页界面。版本说明、构建上传、提交审核、签名证书、订阅价格、分析报表分散在不同入口，每次操作都要登录、找到对应页面、填表、保存。要把这些步骤放进 CI/CD 流水线，就得直接调 App Store Connect API，自己处理认证、请求构造和错误解析。

App Store Connect CLI 是一个用 Go 写的命令行工具，通过 App Store Connect API 管理构建、TestFlight、提交审核、签名与订阅价格，输入命令，输出表格或 JSON。

装好之后，本地多出一个名为 asc 的二进制，官方文档站是 https://asccli.sh。仓库以 MIT 许可证开源，主要语言 Go，占比 96.6%，当前 Star 7544、Fork 636、Watcher 19、开放 Issue 2 条。截至 2026-09-29 的最新版本是 5.8.0。

它解决的是什么问题

没有这个工具时，上架流程的每一步都落在网页后台里完成。改一次版本说明、调一个地区的订阅价格、查一次构建处理状态，都是独立的一次登录加点击。这些动作没法直接写进流水线脚本。

另一条路是调 App Store Connect API。认证方式、请求格式、返回结果的分页与错误结构都要自己处理，出错时还得判断是限流、参数问题还是服务端故障。

asc 把这些收成子命令，让发布动作能以 asc xxx 的形式出现在 shell 脚本和 CI 配置里。仓库的 Topics 包含 cicd、automation、testflight，指向的正是这个用途。

典型使用场景

iOS 或 macOS 团队在 CI 里把构建上传到 TestFlight，等待 App Store Connect 处理完成，再取回 dSYM 做符号化。
面向多个地区发行的产品，需要按国家或地区逐个调整订阅与内购价格，而不是在后台反复切页面。
构建机没有钥匙串访问权限时，用配置文件保存凭据完成上传。
在编码助手（Claude Code、Codex 一类）里跑 asc 工作流，先用 asc install-skills 装上官方维护的技能包。

几个常见疑问

在 CI 或没有钥匙串的机器上认证失败怎么办？

README 的 Troubleshooting 给了两条路径。检查当前配置用 asc auth status --validate，跑健康检查用 asc auth doctor。如果确认是钥匙串被拦，重新执行 asc auth login --bypass-keychain ...，或者在环境里设置 ASC_BYPASS_KEYCHAIN=1。想让凭据只落在当前仓库，加 --local，配置文件写到 ./.asc/config.json。

为什么同一条命令在终端和在脚本里输出格式不一样？

asc 会根据 stdout 连接的位置自动选默认格式：交互式终端用 table，被管道、文件或 CI 接走时用 json。想固定成个人偏好，可以导出 ASC_DEFAULT_OUTPUT=markdown；显式传 --output json 的优先级最高，会覆盖前两者。

提交审核时报错只显示顶层信息，看不到具体原因？

仓库里有一条已解决的 Issue 记录了这个问题：API 返回的响应里带有 meta.associatedErrors，早先的 asc 只打印顶层错误，提交失败的原因因此不透明。该 Issue 状态为已解决。

主要功能

认证与凭据管理：asc auth login 保存团队 API Key，需要 --key-id、--issuer-id、--private-key 三个参数。个人 Key 没有 issuer ID，改用 --key-type individual。
构建与 TestFlight：上传构建、查询处理状态。5.7.0 加入了 dSYM 下载的选择与等待；5.6.0 起，构建等待失败时会一并带出处理详情。
上架提交与元数据：提交审核、读写 listing 文本。5.6.0 允许操作者清空可选的 listing 文本字段，同版本引入 --if-exists。
价格与销售地区：按地区设置应用、订阅与内购的价格和可用性。相关 Issue 记录了按地区定价与 PPP 定价工作流的补齐过程。
分析数据：analytics 相关子命令用于拉取 App Store Connect 的指标数据。
原始请求透传：5.7.0 增加了 raw authenticated request passthrough，用已配置的凭据直接发请求，覆盖还没做成子命令的接口。
Agent Skills：asc install-skills 会检出 review 过的 commit f52c4f04323bb2dfb21ca8be82e6494e9cd0b4d8，把其中的 25 个技能复制到全局 agent-skills 目录。安装前会校验整包和每个文件，失败则回滚，只依赖 git。
服务状态查询：asc system-status 不需要凭据就能查 Apple 开发者服务状态，可以加 --service "App Store Connect" 缩小范围，用 --issues-only 只看事故，或者 --watch --poll-interval 30s 轮询。

安装与最短示例

Homebrew 是 README 推荐的方式：

brew install asc

macOS 和 Linux 也可以用安装脚本：

curl -fsSL https://asccli.sh/install | bash

Windows 走 WinGet，短名和精确 ID 两种写法：

winget install asc
winget install --id Rorkai.ASC --exact

README 说明 WinGet 包仍在等待接受，在 winget search asc 能搜到它之前，Windows 用户可以从 GitHub Releases 页面下载签名后的二进制。已发布的二进制是自包含的，不需要本地装 Go；从源码构建才使用 go.mod 声明的工具链版本。

装完后先确认二进制可用：

asc version
asc --help

接着配置认证：

asc auth login \
  --name "MyApp" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8 \
  --network

API Key 在 App Store Connect 的集成页面生成。第一条业务命令可以是列出账号下的应用：

asc apps list --output table
asc apps list --output json --pretty

关键参数

认证相关：--key-id、--issuer-id、--private-key 是团队 Key 的三件套；--key-type individual 用于个人 Key；--bypass-keychain 让凭据走配置文件而非系统钥匙串；--local 把凭据限制在当前仓库。

输出相关：--output 接受 table、json、markdown，优先级高于环境变量 ASC_DEFAULT_OUTPUT；--pretty 只对 JSON 生效，让输出便于阅读和贴进 bug 报告。

状态查询：--service 指定服务名，--issues-only 只显示事故条目，--watch 配合 --poll-interval 控制轮询间隔，例如 --poll-interval 30s。

条件写入：--if-exists 在 5.6.0 引入，用于只在目标资源已存在时执行操作。

结果在哪里看

命令结果默认打到终端。交互式终端下是表格，被管道或 CI 接走时是 JSON，两者都能用 --output 覆盖。构建这类处理类操作的结果，要么是命令返回的状态，要么是下载到本地的产物，比如 dSYM。

凭据与配置的状态用 asc auth status --validate 和 asc auth doctor 查看。遥测是否开启用 asc telemetry status 查看，需要关闭时执行 asc telemetry disable，重置安装 ID 用 asc telemetry reset-id。发布二进制的下载入口在项目的 GitHub Releases 页面。

实际使用中的坑

下面几条来自仓库的 GitHub Issue，都已关闭，写出来是为了说明这个工具在真实使用中暴露过什么问题。

提交错误信息不完整：API 返回 meta.associatedErrors 时，早先的版本只打印顶层错误，提交失败的具体原因看不到。已解决。
地区可用性查询被截断：asc pricing availability territory-availabilities 的结果上限 50 条，且没有分页参数，地区多的账号拿不全数据。已解决。
没有现成记录时建不了可用性：asc pricing availability set 在应用尚不存在 availability 记录时创建失败，0.40.1 版本上报过。已解决。
同步订阅价格时遇到 API 抖动：读写偶发超时或返回 Apple 服务端错误，高层工作流缺少重试与续跑能力。已解决。

仓库还提供了 migrate-to-4-0.mdx 和 migrate-to-5-0.mdx 两份迁移说明，跨大版本升级前可以先读这两份。

和同类的差别在哪

项目	适合谁	部署方式	主要限制	什么情况下选它更合适	项目地址
App Store Connect CLI	需要把 iOS 或 macOS 上架流程接进 CI，并覆盖构建到定价多个环节的团队	Homebrew、安装脚本、WinGet，或从源码构建	默认发送匿名命令级遥测，要停掉得手动关闭；WinGet 包尚在等待接受	一次配置要覆盖构建、TestFlight、提交、签名、定价、分析等多个资源时	App Store Connect CLI
sabby3861/appctl	想避开 Fastlane、用脚本管理版本、TestFlight 与元数据的开发者	仓库没有说明	未逐一核实，仓库描述只列出版本、TestFlight 与元数据三块	目标就是摆脱 Fastlane，把版本与元数据同步脚本化时	sabby3861/appctl
maximbilan/xcloud	主要在 Xcode Cloud 上触发构建、浏览构建记录的开发者	仓库没有说明	从仓库描述看只覆盖 Xcode Cloud 的构建触发与浏览，未涉及提交、定价等资源	只需要 Xcode Cloud 构建这一件事，不需要完整的上架流程覆盖时	maximbilan/xcloud

App Store Connect CLI 的覆盖面比 appctl 和 xcloud 宽，代价是接入前要先在 App Store Connect 生成 API Key，把 key-id、issuer-id 和私钥落到本地或 CI 凭据里，初始化步骤更多。如果团队的目标只是 Xcode Cloud 的构建触发，或者只做版本与元数据同步，功能更窄的工具意味着更少的配置项要维护；反过来，只要有一个环节落到定价、签名或分析上，把流程分散到多个工具的成本就会上升。

焚评：这个项目的量化评分

本项目的选题来自焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分维度	得分
热度动量（权重 25%）	10.0 / 10
开发活跃（权重 25%）	10.0 / 10
社区响应（权重 15%）	10.0 / 10
文档质量（权重 15%）	10.0 / 10
发布节奏（权重 10%）	10.0 / 10
风险控制（权重 10%）	10.0 / 10

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。

App Store Connect CLI：用命令行跑通 iOS 上架流程