企业官网建设流程全解析

ios-builder 是一款面向无 Mac 开发者的 iOS 构建工具，它的builder ios release命令可以把远程构建、上传 App Store Connect、等待处理、分发 TestFlight、提交 App Store 审核这条完整链路压缩成一条命令。无论你用的是 Windows、Linux 还是 macOS，都不需要 Transporter、altool 或 Xcode 就能发布 iOS 应用。本文带你从零走通这条流水线。

一、为什么需要 ios-builder 发布 iOS 应用

传统流程中，上传 TestFlight 或提交 App Store 审核往往被绑死在 Mac + Xcode 上：本地签名、archive、Transporter 上传、再进网页后台手动分发。ios-builder 换了一种思路：

而且API Key 不会离开你的机器：CI Runner 只负责构建和签名，上传动作始终发生在你本地（源码见 internal/asc/uploads.go）。

二、准备工作：4 步完成 ios-builder 初始化

在发布之前，只需要完成一次性配置。

第 1 步：安装并登录 GitHub

builder auth github

第 2 步：初始化项目

在你的 iOS 项目目录下执行，它会自动检测框架（原生 Swift、React Native、Expo、Flutter、KMP）、生成工作流文件并触发首次构建：

builder init

第 3 步：保存 App Store Connect API Key

在 App Store Connect 网页端用户和访问 → 集成 → App Store Connect API创建一个 Admin 角色的团队 Key（AuthKey_XXX.p8），然后：

builder auth apple --issuer-id <ISSUER_ID> --key-id <KEY_ID> --key ~/Downloads/AuthKey_XXX.p8

第 4 步：一条命令搞定 App Store 签名

这是很多人以为必须打开 Mac 的步骤，ios-builder 通过 App Store Connect API 自动完成：注册 App ID、签发 Apple Distribution 证书、创建 App Store Provisioning Profile，并把签名密钥写入 CI Secrets 和 builder.json 的store构建 Profile：

builder signing setup --distribution store

完成这 4 步后，发布链路就全部就绪了。

三、核心命令：builder ios release 完全用法

builder ios release的实现位于 cmd/builder/release.go，完整流程逻辑在 internal/release/release.go。它的执行顺序是：

前置检查 → 解析下一个构建号 → 远程构建并下载 IPA → 校验 IPA → 上传 App Store Connect → 等待处理完成 → 分发 TestFlight或提交 App Store 审核

发布到 TestFlight（默认行为）

builder ios release --profile store --group "Beta Testers" --notes "新登录流程，重点测试注册页"

• 未指定--group时只上传并等待处理完成
• --group可重复传入，把构建加入多个 TestFlight 分组；分组不存在会自动创建（默认内部分组，外部测试用--external创建分组）
• --notes会写入该构建的 "What to Test" 备注

发布到 App Store 并提交审核

builder ios release --profile store --app-store --release after-approval

• --release manual：审核通过后手动发布
• --release after-approval：审核通过自动上线（推荐）
• 注意：应用元数据（截图、描述、年龄分级、隐私声明）必须先在 App Store Connect 中填好，否则 Apple 会拒绝提交，ios-builder 会把 Apple 返回的拒绝原因原样打印给你

最简快捷方式

如果只想快速发一个不带分组的 TestFlight 构建，还有更短的写法：

builder ios build --profile store --submit

它等价于一次不带--group的 release。

常用参数一览

四、构建号自动递增，告别 ITMS-90189

Apple 的铁律是：同一应用同一版本的 CFBundleVersion 必须递增，重复上传会直接被拒（错误码ITMS-90189）。手动管理构建号最容易出事故。

ios-builder 的解法很直接：查询 App Store Connect 中该应用所有版本已存在的最高构建号，自动 +1 再构建（新应用则为1）。构建完成后它还会读取产出的 IPA 反查校验——如果 Runner 没有成功应用该构建号，上传会被提前拦截并给出原因，而不是把问题留到 Apple 那边才暴露。实现逻辑参考 internal/release/release.go 中的NextBuildNumber。

这意味着你几乎可以每天跑一遍 release 命令，构建号永远合法。

五、不想一步到位？拆分命令同样好用

release 是"打包"，但每个环节也可以单独执行，适合已有构建产物或想人工把关的流程：

# 1. 构建并签名 builder ios build --profile store # 2. 上传 ./dist/ 最新 IPA 并等待处理完成 builder ios upload --wait # 3. 分发到 TestFlight builder ios submit --testflight --group "Beta Testers" --notes "重点回归支付页" # 3'. 或提交 App Store 审核 builder ios submit --app-store --release after-approval

这些命令都支持--json且从不交互询问，非常适合写进 CI 定时任务，实现"每晚自动出一个内测包"。

六、TestFlight 分组与测试员管理

发布只是开始，测试人员的管理也可以不进网页后台（源码位于 internal/asc/）：

builder asc groups # 查看所有分组及测试员数量 builder asc groups create Nightly # 创建内部分组 builder asc testers add a@example.com --group Nightly --first Ann --last Lee builder asc builds expire --build-number 42 --yes # 清理过期构建

两个实用细节：

• 内部分组只接受团队成员，testers add会自动把陌生人先邀请进 App Store Connect 团队，对方接受邮件后才能收到构建
• 分组名大小写不敏感匹配，若存在仅大小写不同的两个分组会拒绝执行并列出两者，避免误操作

七、常见问题 FAQ

Q：release 报错说没有 store Profile？运行builder signing setup --distribution store，它会自动创建签名集并写入storeProfile。错误信息本身也会直接提示这条命令。

Q：上传被拒，提示 Debug 包？storeProfile 默认以 Release 配置构建，如果你手动在 builder.json 的 Profile 里写了"configuration": "Debug"会被前置检查拦截——App Store Connect 只接受 Release 归档。

Q：构建或处理超时了怎么办？--timeout分别约束"构建"和"App Store 处理"两个阶段（各默认 30 分钟），大型应用可以调大到--timeout 1h。超时会明确告诉你卡在哪个阶段。

Q：不想用 GitHub Actions？--provider codemagic或--provider bitrise可以切换 CI 供应商，登录互不干扰，详见 docs/providers.md 与 docs/provider-secrets.md。

Q：构建会提交我的代码吗？不会。ios release推送的是工作区的临时快照到隐藏引用，构建结束后即删除；未提交、未跟踪的文件都会被构建，.gitignore依然生效，也不会替你创建任何分支。

小结

ios-builder 把"远程构建 → 自动签名 → 自动构建号 → 上传 → 分发/提审"整条链路收敛到一条命令里，是 Windows/Linux 开发者发布 iOS 应用到 TestFlight 与 App Store 最顺滑的路径。更多命令细节可参考仓库中的 README.md 与 cmd/builder/release.go。