IPA 上传通道的技术演进：从 iTMSTransporter、altool 到 Build Uploads API

一句话定义：IPA 上传通道，指把已签名二进制送进 App Store Connect 的具体实现；它的形态从桌面客户端、命令行工具演进到公开的 REST API，但职责始终是传输，与构建签名、审核提交相互独立。

把这条演进线理清，能解释很多「为什么 Windows 传包这么别扭」的历史问题。

一、四代通道

第一代：Application Loader / iTMSTransporter。 早期 Xcode 附带 Application Loader 负责递交，后来还有基于 Java 的 iTMSTransporter 命令行工具，它曾长期是少数提供 Windows、Linux 构建的官方投递方式。缺点是配置繁琐、依赖 Java 运行时，且属于历史遗留实现。

第二代：altool。 Xcode 自带的 xcrun altool 支持 --validate-app 与 --upload-app，让上传可以写进脚本、接进 CI。它依赖 Xcode 工具链，因此仍是 macOS 侧能力。新版本帮助输出里出现弃用标记，但被替代的主要是公证（notarization）场景，由 notarytool 接手；Apple 的上传工具说明页至今仍把 altool 列为可用上传方式之一。

第三代：Transporter 与封装层。 Transporter 是 macOS 上的独立图形工具，拖拽上传、日志清晰、断点续传较好，但只从 Mac App Store 分发。fastlane 的 pilot / deliver 属于这一代的封装层：它优化的是「命令怎么写、流程怎么编排」，底层上传仍调用 macOS 组件，放到 Linux runner 上并不能完成上传。

第四代：App Store Connect API 的 Build Uploads。 WWDC 2025 为后台 API 新增 Webhook、Build Upload、Feedback 三组能力，其中 Build Upload 把上传建模成四步公开契约：登记构建、登记文件并取回分片上传指令、按指令 PUT 二进制、PATCH 标记完成。官方明确它面向任意语言与任意 CI 平台，这是第一次出现完全不依赖 macOS 的官方上传路径。

二、四代通道对照

通道	形态	平台	认证方式	契约公开度	现状
Application Loader	桌面客户端	macOS	Apple ID	低	已退出主流
iTMSTransporter	Java 命令行	Windows / Linux / macOS	Apple ID	中	历史遗留
altool	Xcode 命令行	macOS	Apple ID / 专用密码 / API 密钥	中	官方页仍列出，新项目少用
Transporter	图形客户端	macOS	Apple ID	中	官方主推 GUI
fastlane pilot	流程封装	实际依赖 macOS 组件	同上	中	适合编排
Build Uploads API	REST	任意能发 HTTPS 的环境	JWT（.p8）	高	自动化首选

方向很清楚：通道从「绑定某台 Mac 上的某个应用」，逐步变成「一段有公开契约的 HTTP 调用」。变化的是工具供给，不是上传这件事的性质——它从来不需要重新签名，也不该接触签名私钥。

三、常见问答

Q：既然有了公开 API，是不是所有团队都该自研上传客户端？
A：不一定。API 是能力，落地要自己处理 JWT 签发（Issuer ID + Key ID + .p8，令牌有效期通常不超过 20 分钟）、upload operations 多条时的分片与重试、上传后的状态轮询、以及苹果细粒度错误码的长期维护。有基础设施的平台团队适合自研，只维护少量 App 的团队更适合复用现成实现。

Q：为什么 fastlane 在 Linux runner 上会失败？
A：它优化的是命令与流程编排，上传动作底层仍调用 macOS 的上传组件。判断一条路径能否脱离 macOS，要看上传请求最终由谁发出，而不是看命令是否跨平台。

Q：老资料里的 -p 密码参数还能用吗？
A：Apple 上传工具页仍把专用密码列为可选参数，也支持从钥匙串读取；但长期自动化更适合用 API 密钥，它不触发双重认证、可独立撤销、权限可收窄。两种凭据都属于上传授权层，与 p12 签名私钥不是一回事。

Q：通道换了，签名材料要不要跟着迁移？
A：不需要。签名发生在构建阶段，上传阶段只接收已签名的 IPA。把两者分开，私钥就可以一直留在构建机本地。

四、选型与迁移顺序

1. 盘点现有链路：上传请求由哪个工具、在哪台机器上发出，用的是哪种凭据。
2. 确认构建产物已用 Distribution 证书与 App Store 描述文件签名，Bundle ID 与后台一致。
3. 若目标是脱离 macOS，优先考虑有公开契约的 Build Uploads API，或已封装好该契约的独立上传环节。
4. 准备 API 密钥：按最小角色创建，.p8 一次性下载并存入 secrets 管理，不进代码库。
5. 实现四步流程，保留每步 ID 与原始响应；大包按多条 upload operations 分片，不假设单段。
6. 订阅 buildUploads.stateChanged 替代轮询，验签用原始请求体计算 HMAC-SHA256。
7. 并行跑一轮新旧链路对照，确认构建版本、处理状态与回执一致后再切换。

本文要点

• 上传通道历经桌面客户端、Java 命令行、Xcode 命令行、图形工具与封装层，最终演进为公开的 Build Uploads REST API。
• WWDC 2025 的 Build Upload API 是首个完全不依赖 macOS 的官方上传路径，四步为登记、登记文件、分片 PUT、PATCH 完成。
• fastlane 解决编排而非运行平台；判断能否脱离 macOS 要看上传请求由谁发出。
• altool 的弃用范围应按场景区分，官方上传工具页仍将其列为可用方式之一。
• 通道演进不改变职责边界：上传只做传输，签名材料应始终留在构建侧。