App Store 发布 是做什么的?
通过 App Store Connect API 驱动完整的 iOS App Store 提交流程。设计目标:用户一次性提供凭据 + config.json,然后智能体自动执行所有可自动化任务,仅在 Apple 确实未通过 API 暴露的少数步骤中断用户。不要要求用户重新确认已存在于配置中或具有合理默认值的内容。
运行原则(先阅读此部分)
- 配置驱动,非提示驱动。 所有应用内容都存在于
config.json中。执行命令;不要盘问用户。 - 仅有两项为纯 UI 操作(Apple 无 API):App 隐私数据收集 和 首次订阅绑定 + 提交。工具会检测到这些操作并给出精确的点击指引,其余均可脚本化。
- 仅在以下情况下询问用户:配置缺少必需字段(明确告知哪个字段)、配置中没有的业务决策(订阅价格、发布时间)、或执行唯一不可逆操作(最终提交)前。否则继续执行。
- 幂等性:每条命令都可安全重复运行。
node cli.mjs release可以反复执行。
架构(SOLID,便于扩展)
scripts/
cli.mjs 单一入口/调度器(node cli.mjs <command>)
lib/ 注入的服务,每个单一职责
env.mjs 解析+验证环境变量(凭据、应用 ID)
jwt.mjs ES256 令牌提供者
client.mjs AscClient — 认证 + HTTP + 统一错误处理
discovery.mjs 通过自然键定位 ASC 资源(无硬编码 ID)
assets.mjs 预留→上传→提交的二进制上传器
config.mjs 加载+验证配置,列出缺失项
log.mjs 结构化结果 + 机器可读摘要
context.mjs 组合根(依赖注入)
commands/ 每个任务一个文件;统一契约(见 _contract.md)
添加一个能力 = 添加一个 commands/x.mjs(元数据 + run(ctx))并在 cli.mjs 中注册。
设置(一次性)— 见 references/setup.md
- ASC API 密钥(App Manager):下载
AuthKey_XXXX.p8,记下密钥 ID 和颁发者 ID。 - 在 ASC 中存在应用记录(bundle id 已注册)。
ASC_APP_ID= 应用 ASC URL 中的数字 ID。 - EAS 项目已配置,
eas login已完成。 - 根据
references/config-template.json填写config.json。随时验证:任何命令都会打印出具体缺少的字段。
环境变量
export ASC_KEY_ID=... ASC_ISSUER_ID=... ASC_P8_PATH=/abs/AuthKey_XXXX.p8 # 将 .p8 加入 gitignore
export ASC_APP_ID=1234567890
export APPSTORE_CONFIG=/abs/config.json
cd scripts # 然后:node cli.mjs <command>
运行手册
1. 了解现状
node cli.mjs status # 完整的只读概览
node cli.mjs check # 就绪状态 + 仍需完成的 UI 操作
2. 构建二进制文件 (EAS)
- 如果
eas build因凭据过期失败(“provisioning profile expired / no certificate with serial…”):然后在 eas.json 的生产配置中设置node cli.mjs credentials # 生成新的分发证书 + 配置文件 → credentials.json"credentialsSource":"local"。 - 构建并提交二进制文件(为无交互模式设置
EXPO_ASC_API_KEY_PATH/KEY_ID/ISSUER_ID+EXPO_APPLE_TEAM_ID+EXPO_APPLE_TEAM_TYPE):等待构建状态变为 VALID(eas build -p ios --profile production --non-interactive --no-wait eas submit -p ios --profile production --id <buildId>node cli.mjs status)。
3. 一次性填写整个列表信息
node cli.mjs release # 关联构建 → 元数据 → 定价 → 版权声明 →
# 年龄分级 → 类别 → 审核信息 → 截图 →
# 订阅 → 检查
release 运行整个流水线(幂等),并以 check 结束,该命令会打印出剩余的 仅 UI 步骤。截图必须事先存在(config.screenshots.dir)— 见 references/screenshots.md 了解生成方法。
4. 两个仅 UI 的步骤(提供精确点击指引)
check 会在适用时列出这些步骤:
- App 隐私 → 数据收集:声明与应用隐私清单匹配的数据类型,然后发布。⚠️ 如果二进制文件包含
NSUserTrackingUsageDescription但未声明任何跟踪,则发布会被阻止 → 移除该键并重新构建(references/gotchas.md)。 - 首次订阅:版本页面 → App 内购买项目和订阅 → 选择 → <产品> → 保存 → 添加至审核 → 提交。(API 无法绑定首次订阅。)
5. 提交
node cli.mjs check # 确认没有遗漏
node cli.mjs submit --submit # 仅应用/更新(不包括首次 IAP)
对于首次订阅,用户需在 UI 中提交(步骤 4.2)。通过 status 验证:版本和订阅状态均为 WAITING_FOR_REVIEW。
拒绝处理
被拒绝后,版本变为可编辑状态(REJECTED/METADATA_REJECTED/DEVELOPER_REJECTED)。阅读解决方案中心消息,修复问题(元数据问题通过 release 修复,二进制问题需重新构建),然后重新提交。
参考资料
references/setup.md— 密钥创建、应用记录、EAS、凭据安全。references/gotchas.md— 所有常见陷阱(首次运行前阅读)。references/screenshots.md— 生成精确尺寸的 PNG(HTML → headless Chrome)。references/config-template.json— 每个应用的配置(由lib/config.mjs验证)。