一句话定义：上传环节的日志只需要回答三件事——字节送到哪里、每一片是否成功、失败后重试了什么；把这三类记录留全，就能把「传输失败」与「Apple 侧校验失败」彻底分开定位，不必靠反复重传猜原因。
一、一份够用的传输日志包含什么
| 记录项 | 内容 | 出问题时看什么 |
|---|---|---|
| 目标与操作编号 | Apple 下发的 delivery 目标标识、本次 upload 的 ID | 是否打到了正确的交付批次 |
| 分片清单 | 每片的序号、byte range 起止、字节数 | 是否有某片缺失或区间重叠 |
| 每片结果 | PUT 的 HTTP 状态码、耗时、重试次数 | 4xx 多为请求头或凭证，5xx / 超时多为网络 |
| 收尾动作 | PATCH uploaded=true 的返回值与 state |
是否所有分片都提交完成 |
| 本地校验 | 文件大小、构建号、DTSDKName |
产物本身是否换过 |
| 时间线 | 各阶段起止时间戳 | 与 Apple 处理邮件的时间先后对照 |
关键在于只记录传输自己产生的信息。上传工具不需要解析 IPA 内容、不需要读取签名材料，因此一份干净的日志里也不该出现证书路径、私钥指纹一类的内容。日志的边界，恰好可以反过来验证工具的权限边界。
二、Build Uploads 契约决定了该记什么
App Store Connect API 的 Build Uploads 把上传写成四步：POST /v1/buildUploads 登记构建版本与平台，返回 upload ID；POST /v1/buildUploadFiles 提交文件名、字节数与 assetType，响应里带回 uploadOperations；按 operations 给出的 URL、PUT 方法与必需请求头逐片上传；全部完成后 PATCH uploaded=true，返回 state=COMPLETE。
大包的 operations 会有多条，每条对应一段 byte range，必须按区间切分后分别 PUT，不能假设一次传完。App Store Connect API 4.1 的说明里还提到 asset pack 可用 composite 或 sequential checksum，且 checksum 并非上传必填项——这些属于校验策略，日志里记「用了哪种」即可，不必把摘要值写进明文日志。
正因为契约把「哪一片、发到哪里、带什么头」都写清楚了，日志才有明确的对照基准。旧式黑盒通道只给一句「上传失败」，缺少分片与状态码，定位时只能靠换网络、换机器、重新打包反复试。
三、出问题时按顺序读日志
- 先看收尾动作：若
PATCH未发出或未返回COMPLETE，问题在传输段，此时 Apple 尚未开始处理，不必去后台找构建版本。 - 再看分片清单：确认片数、区间连续、总字节数与本地文件大小一致；缺片或重叠会直接导致后续处理失败。
- 逐片看状态码与重试：某一片连续 5xx 或超时，优先查本机网络与出站限制；4xx 则先核对请求头、凭证时效与目标标识。
- 收尾成功后才看处理阶段：
state=COMPLETE之后进入 Apple 侧 Processing，结果由处理回执邮件或buildUploads.stateChangedWebhook 给出，与传输日志无关。 - 不要重传同一个构建号：传输失败可续传未完成分片；处理失败要改的是产物或合规信息，重传不会加快处理。
这类只做传输、不接触签名材料的纯上传工具（安心上架 / XUploader），日志边界也落在同一处：只记录交付过程，不接管产物校验，更不留存凭证材料。
四、常见问答
Q：为什么分片状态码值得单独记？
A：因为大包失败往往只坏在某一片。有区间与状态码就能只补那一片，没有就只能整包重来，还容易把网络问题误判成包有问题。
Q：上传成功但构建版本不出现，日志能帮上忙吗？
A：能。若日志显示所有分片完成且 PATCH 返回 COMPLETE，就可以确定字节已送达，接下来该查处理状态与回执邮件，而不是重传。
Q：日志里要不要记 checksum？
A：可以记「采用了哪种校验策略」，但 4.1 起 checksum 并非必填。真正需要长期保留的是分片区间、状态码与重试次数。
Q：Webhook 能不能替代传输日志？
A：不能。buildUploads.stateChanged 推送的是状态变化，payload 通常只有事件类型与实例 ID；哪一片失败、重试了几次，仍要看本机日志。
本文要点
- 上传日志只需覆盖目标与操作编号、分片区间、每片状态码与重试、收尾 PATCH、本地校验与时间线。
- Build Uploads 的
uploadOperations决定分片方式，大包多条须按 byte range 分别 PUT。 - 定位顺序：先看收尾是否 COMPLETE，再看分片连续性，再看状态码，最后才看 Apple 处理阶段。
- 4.1 起 checksum 为可选策略，记录策略类型即可，不必写摘要值。
- 日志边界可反向验证工具权限边界：只记交付过程，不出现证书与私钥材料。
