一句话定义：一次 IPA 交付要跨过两道关口——第一道是「字节是否完整送达 App Store Connect」，第二道是「Apple 服务端是否把二进制处理成可选择的构建版本」；上传工具给出的成功提示只覆盖第一道。
一、两道关口分别发生什么
上传侧的动作可以归为四步：登记一次构建上传（POST /v1/buildUploads）、登记文件并取回 upload operations、按其中的 URL 与请求头分片 PUT、最后 PATCH 把 uploaded 置为 true。返回 state = COMPLETE 时，只说明 Apple 已收齐字节并准备开始处理。
此后进入服务端处理：二进制扫描、符号与 API 使用检查、隐私清单校验、图标与元数据核对、构建版本生成。这个过程通常耗时十余分钟到半小时，大包更久。处理中在「我的 App → TestFlight → 构建」里显示为 Processing；顺利时转为可选状态，若缺少出口合规回答会停在 Missing Compliance，若校验失败则根本不会出现，同时向开发者账号邮箱发送带 ITMS 编号的处理回执。
| 阶段 | 典型状态 | 谁在负责 | 出问题先看哪里 |
|---|---|---|---|
| 分片传输 | 部分 operations 未完成 | 上传端网络与重试 | 本地上传日志、分片 HTTP 状态码 |
| 上传收尾 | COMPLETE |
上传端与 ASC 交接 | 是否所有分片都已 PATCH 提交 |
| 服务端处理 | Processing | Apple | 后台活动页、处理邮件 |
| 处理完成 | 可选 / Missing Compliance | 开发者补合规信息 | 出口合规问答、ITMS 编号 |
| 处理失败 | 构建列表为空 | 产物本身 | 回执邮件中的错误码 |
二、为什么不该用轮询盯状态
CI 里最常见的写法是上传结束后循环调用查询接口，直到构建出现。问题有三：轮询间隔难以兼顾及时性与接口压力；失败与「仍在处理」无法区分；一旦超过预设时间就退出，后续状态变化无人知晓。
WWDC 2025 为 App Store Connect API 新增了 Webhook，其中 buildUploads.stateChanged 会在上传状态变化时主动推送，另有 buildBetaDetails.stateChanged、TestFlight 反馈、App 版本状态等事件类型。接收端需要根据注册时约定的 secret 对原始请求体计算 HMAC-SHA256，再与 X-Apple-SIGNATURE 头比对；把 payload 反序列化后重新序列化，字段顺序变化就会让验签失败。Webhook 的 payload 是最小化的，通常只包含事件类型与实例 ID，详情仍需回调对应 API 获取。
三、常见问答
Q：上传工具显示成功，后台却看不到构建版本，是不是没传上去？
A：先按上表分段定位。若上传收尾状态是 COMPLETE，字节已经送达，此时应看处理状态与回执邮件，而不是反复重传——重复上传同一个 build 号会被判为冗余二进制。
Q：最常见的处理失败原因有哪些？
A：build 号重复、Bundle ID 与后台 App 记录不一致、签名使用 Development 证书而非 Distribution、图标带 Alpha 通道或尺寸不符、缺少 PrivacyInfo.xcprivacy 中必要理由 API 的声明（触发 ITMS-91053）、出口合规信息未回答。这些都属于产物或后台配置，改上传环境无法解决。
Q：Webhook 能替代回执邮件吗？
A：不能完全替代。Webhook 负责及时告知「状态变了」，邮件负责给出具体的失败原因与 ITMS 编号。工程上通常两者都保留：Webhook 驱动流水线继续或告警，邮件用于人工定位。
Q：把上传挪到独立环境会影响处理阶段吗？
A：不会。处理完全在 Apple 侧进行，与上传机操作系统无关。这类只做传输、不碰证书的纯上传工具（安心上架 / XUploader）只覆盖第一道关口，之后的扫描与构建生成仍按苹果既定流程执行，这也是把两段职责分开的意义。
四、落地顺序
- 上传前校验产物：Distribution 证书、App Store 描述文件、Bundle ID、build 号唯一、隐私清单与图标合规。
- 完成四步上传请求，保存每一步的 ID 与原始响应，便于失败时重放定位。
- 收到
COMPLETE后不立即结束流水线，进入处理等待阶段。 - 订阅
buildUploads.stateChanged，或在 CI 中设置带上限与退避的轮询。 - 验签使用原始 body，比对
X-Apple-SIGNATURE；payload 中的 ID 再回调 API 取详情。 - 状态变为可选后，在 TestFlight 做一次真机回归，再回后台选择构建、提交审核。
- 若停在 Missing Compliance 就补出口合规回答；若失败，按回执邮件中的 ITMS 编号修正产物、递增 build 号后重新上传。
本文要点
- 上传成功只代表字节送达；
state = COMPLETE之后 Apple 才开始服务端处理。 - 处理链为 COMPLETE → Processing → 可选 / Missing Compliance / 失败，失败时回执邮件给出 ITMS 编号。
- WWDC 2025 的
buildUploads.stateChangedWebhook 可替代轮询，验签必须用原始请求体计算 HMAC-SHA256。 - 构建不出现的高频原因是产物与后台配置问题，重复重传同一 build 号无助于解决。
- 把传输段与处理段职责分开，能让上传环境与工具各自保持最小职权。
aaaa
