-22938 与 User-Agent：第三方 IPA 上传通道的兼容性陷阱

一句话定义：-22938 是一类上传失败码，常见于第三方工具复用了未公开文档化的投递接口时，请求头格式与服务端预期不一致；它属于通道兼容性问题，与 IPA 本身的签名、版本号和元数据无关。

一、现象：包没问题，上传却失败

开发者社区里记录过一类典型案例：同一个已签名 IPA，在某一版上传工具里稳定报 -22938，换一台机器、换网络、重新打包都无法复现解除；排查到最后，触发点是工具发出的 User-Agent 请求头格式不符合接收端的隐式校验。

这类问题的麻烦在于，失败信息不指向具体字段，日志里往往只有一串数字。若按常规思路去查证书过期、Bundle ID 不匹配、build 号重复，会白白消耗一轮打包与上传的时间。

二、根因：黑盒通道依赖隐形约定

非官方的投递实现，常见做法是模拟官方客户端的请求序列。序列里除了公开的 URL 与参数，还会带上若干未写进文档的请求头约定：User-Agent 的具体格式、某些自定义头的顺序、分块上传时的头继承规则等。服务端一旦调整校验，客户端没有公开契约可依据，只能在报错后逐项猜测。

与之相对，App Store Connect API 的 Build Uploads 资源有公开契约：POST /v1/buildUploads 登记构建，POST /v1/buildUploadFiles 取回 upload operations，按其中给出的目标 URL、HTTP 方法与必需请求头逐条 PUT，最后 PATCH 标记完成。请求头由服务端在响应里显式给出，实现方不需要猜。

三、常见问答

Q：出现 -22938，第一步该做什么？ A：先确认产物本身无嫌疑——上传前用 --validate-app 之类的静态校验跑一遍，或在另一条独立通道上试传同一个包。若只有特定工具失败，基本可以判定是通道兼容性而非产物问题。

Q：改 User-Agent 就能彻底解决吗？ A：只能解决当次。只要实现依赖的是未公开的隐式约定，服务端后续调整仍可能再次触发同类问题。把它当作临时绕行，长期方案是迁到有公开契约的接口。

Q：这会影响 App Store Connect 里的构建版本吗？ A：不会。请求在传输阶段就被拒，字节没有送达，服务端不会开始处理，也就不会产生新的构建或消耗 build 号。但重复失败重试仍要注意 build 号唯一性，避免后续成功上传时撞号。

Q：怎么区分传输失败与服务端处理失败？ A：看是否有上传收尾状态与处理回执。传输失败通常发生在本地日志，后台无新构建、邮箱无处理邮件；处理失败则能看到 Apple 发出的带 ITMS 编号的回执，错误指向二进制或合规声明。

四、排查与迁移顺序

1. 固定变量：同一个 IPA、同一个网络、同一组账号凭据，只更换上传通道做对照。
2. 记录完整请求与响应（脱敏后保存），重点比对请求头、分块大小与重定向行为。
3. 用静态校验确认签名证书类型、Bundle ID、build 号、图标与隐私清单无问题，排除产物侧因素。
4. 若确认是请求头约定导致，短期可通过修正客户端实现绕行，但不要把它当作长期依赖。
5. 迁移到公开契约通道：准备 API 密钥（按最小角色创建、.p8 一次性下载并存入 secrets 管理），实现四步上传流程。
6. 严格按 upload operations 里返回的 URL、方法与请求头发起分片，不自行拼装未文档化的头。
7. 订阅上传状态变更事件替代轮询，失败时以响应体中的错误对象为主要依据。
8. 保留新旧通道并行对照一轮，确认构建版本与处理回执一致后再下线旧实现。

五、可复用的判断原则

• 错误信息只有数字码、没有字段说明时，优先怀疑通道而非产物。
• 依赖隐式约定的实现，维护成本会随服务端演进而上升。
• 请求头由服务端显式下发的接口，比「模拟客户端」更容易做回归测试。
• 传输层问题与二进制校验问题要分开定位，避免把打包流程反复重跑。

本文要点

• -22938 常见于第三方通道的请求头约定不匹配，User-Agent 格式是已记录的触发点之一。
• 根因是黑盒实现依赖未文档化的隐式约定，服务端调整后客户端会静默失效。
• 公开契约的 Build Uploads API 由响应显式下发请求头，错误对象带字段说明，长期维护更可控。
• 排查顺序：固定变量做通道对照 → 静态校验排除产物 → 抓包比对请求 → 迁移公开接口。
• 传输失败不产生构建版本；处理失败才有 ITMS 回执，两者定位路径完全不同。