流水线显示成功，只说明脚本退出码为0，不能直接当作构建结果有效。遇到制品缺失或版本不符，复核的关键是建立一条从产物生成到下游取用的证据链：先界定症状和影响范围，再按构建、上传、版本、下游四段逐项核对，最后用制品库中的实际文件和部署验证结果给出确认结论。
要点总览（TL;DR）
- 流水线显示成功只代表脚本退出码为0，复核时要按“产物是否生成—是否上传到制品库—版本与坐标是否一致—下游是否取到同一份制品”四段逐项核对证据。
- 先界定症状类型和影响范围：制品库无文件、版本号或构建号不符、下游取到旧版本，三类问题的排查入口不同。
- 版本不符时以制品库中的版本元数据为准，比对流水线变量取值与构建号规则，流水线界面显示的版本号只作参照。
- 确认结论需要制品库实际文件、版本元数据、校验值和部署验证结果相互印证，可表达为有效、无效需重跑、部分有效需补充发布。
- 减少误判可把制品存在性与版本一致性纳入成功判定，增加发布后校验，并保留构建与制品的关联记录。
症状与范围：先分清制品缺失、版本不符还是下游取错
“构建成功但有问题”是一个笼统描述，直接排查容易在错误的方向上耗费时间。第一步应把症状拆成可核对的具体类型，并记录定位信息，为后续排查划定边界。
典型症状可以归为三类：
- 制品库无对应文件：流水线报告成功，但按预期坐标在制品库中检索不到任何文件，或只有历史版本。
- 版本号或构建号不符：制品存在，但其版本号、构建号与流水线记录不一致，可能是版本号取自错误变量，也可能是旧制品被复用。
- 下游取到旧版本或错误坐标：部署或验证环节引用的版本、仓库地址与本次构建不一致，导致运行的不是本次产物。
登记症状时，至少记录以下定位信息：流水线名称与运行编号、提交哈希、构建时间、制品坐标（group/artifact/version）、目标环境。这些信息是后续在日志和制品库中检索的索引，缺一项就可能在比对时失去参照。
影响范围决定排查的优先级。需要判断问题出现在单条流水线还是多条流水线、单个制品还是整批制品、是否已经进入部署阶段。如果制品已流入测试或生产环境，排查的同时要先控制影响面，避免错误版本继续扩散。
| 症状类型 | 关键定位信息 | 影响范围判断 |
|---|---|---|
| 制品库无对应文件 | 流水线运行编号、制品坐标、构建时间 | 单制品缺失还是整批缺失；是否影响下游部署 |
| 版本号或构建号不符 | 提交哈希、版本变量取值、制品库版本元数据 | 单条流水线版本规则问题还是多条共用规则问题 |
| 下游取到旧版本或错误坐标 | 部署引用的版本、仓库地址、目标环境 | 是否已进入测试或生产；影响哪些环境 |
原因假设与排查顺序：从产物生成到下游取用的四段证据
排查应按构建链路的先后顺序推进，逐段用证据验证假设，避免跳段猜测。每一段都有对应的验证材料，只有前一段被证实，后一段的结论才有意义。
第一段：构建步骤是否真的产出了目标文件
查看构建日志中的产物路径与文件清单，确认目标文件确实被生成。常见情况是构建脚本执行了部分任务后提前结束，或产物输出到了与预期不同的目录。此段的证据是日志中的文件列表和路径，而非“构建成功”的状态标记。
第二段：上传或发布步骤是否执行成功
产物生成不等于已进入制品库。需要查看上传日志、制品库的接收记录，以及是否存在权限报错。上传步骤被条件分支跳过、凭据失效、仓库地址配置错误，都会造成“构建成功但制品库没有文件”。此段要区分“没有执行上传”和“执行了但失败”两种情况。
第三段：版本与坐标是否一致
比对流水线变量取值、构建号规则与制品库中的实际版本元数据。版本号取自错误变量、构建号规则在分支间不统一、缓存或旧制品被复用，都会导致版本不符。核对时以制品库中的版本元数据为准，流水线界面显示的版本号只作为参照。
第四段：下游是否取到同一份制品
核对部署或验证环节引用的版本号与仓库地址，确认其指向本次构建产出的那一份制品。下游配置了固定版本号、缓存了旧坐标，或引用了另一个仓库，都会造成取错。
常见误判来源集中在几处：上传步骤被跳过或条件不满足、版本号取自错误变量、缓存或旧制品被复用、成功判定只看退出码。这些假设需要通过上述四段证据逐一证实或排除，不能凭经验直接下结论。
| 排查段落 | 原因假设 | 验证证据 |
|---|---|---|
| 产物生成 | 构建脚本提前结束、输出目录错误 | 构建日志中的产物路径与文件清单 |
| 上传发布 | 上传步骤被跳过、凭据失效、仓库地址错误 | 上传日志、制品库接收记录、权限报错 |
| 版本坐标 | 版本变量取值错误、构建号规则不统一、旧制品复用 | 流水线变量、构建号规则、制品库版本元数据 |
| 下游取用 | 引用固定旧版本、缓存旧坐标、仓库地址不一致 | 部署配置中的版本号与仓库地址 |
复核处置步骤：按证据逐项排除并修正
复核动作按顺序执行，每一步都有明确的判断标准。前一步未通过时，先处理该段问题，不急于进入下一步，避免在错误前提上继续操作。
- 核对构建日志中的产物清单。将日志中的文件列表与预期产物逐项比对。判断标准：目标文件存在且路径正确。若缺失，停止后续步骤，先修正构建脚本或输出配置。
- 在制品库中按坐标检索实际文件。确认文件存在性、上传时间戳与文件大小。判断标准：存在与本次构建时间匹配的文件。若不存在，进入上传环节排查。
- 比对版本号与版本元数据。将流水线记录的版本号与制品库中的版本元数据对照。判断标准：两者一致，且版本号来源变量取值正确。若不一致，定位版本变量的定义位置并修正。
- 检查上传步骤的配置、凭据与条件分支。确认上传步骤在当前分支和条件下确实被执行，凭据有效，仓库地址指向目标制品库。判断标准：上传日志显示成功接收，无权限或网络报错。
- 核对下游引用的版本与仓库地址。确认部署或验证配置引用的是本次构建的版本，而非固定旧版本或另一仓库。判断标准：下游取到的制品与制品库中本次构建的文件一致。
涉及重新构建或覆盖发布时，需要先明确风险边界。覆盖发布前应保留旧版本或做好备份，确认下游可以回退；重新构建应使用同一提交哈希，避免引入新的变更干扰比对。若问题已影响生产环境，先停止继续发布，待证据链完整、修正验证通过后再恢复。停止点设在“证据不足以下结论”和“修正动作可能影响已发布版本”两处。
复核过程中的结论、重跑记录和制品关联信息需要在工作项中留痕，便于交接和后续追溯。采用 ONES 并集成 Jenkins、GitLab CI 等第三方流水线工具时，流水线数据会同步到 ONES，执行状态和日志可在项目、迭代、需求中查看，复核结论与重跑记录可以随工作项一并保留，减少口头交接造成的信息丢失。
确认结论与复发预防：用什么证据判定构建结果有效
确认构建结果有效，需要一组相互印证的证据，单凭流水线状态或制品库中存在文件都不充分。建议的证据组合包括：制品库中的实际文件、版本元数据、文件校验值，以及部署或验证环境的运行结果。四类证据指向同一份制品时，结论才可靠。
结论可以按三种方式表达：
- 有效：制品存在、版本一致、校验值匹配、下游验证通过，四项证据齐全。
- 无效需重跑：产物未生成或上传失败，且无法通过补充发布修复，需修正后重新构建。
- 部分有效需补充发布：产物已生成但未上传，或上传成功但下游未更新，通过补充上传或重新部署即可闭环。
减少同类误判，可以从三个方向改进。其一，把制品存在性与版本一致性纳入流水线的成功判定，让“成功”包含制品校验结果，而不只是脚本退出码。其二，在发布后增加校验步骤，自动比对制品库中的版本与下游实际运行的版本。其三，保留构建与制品的关联记录，使每次构建对应的制品坐标、版本和校验值可追溯。
这些改进需要结合团队现有工具链条件选择落地方式。ONES 支持在项目、迭代、需求中可视化代码提交、流水线构建、产品发布等 CI/CD 过程，并提供数据报表追溯 DevOps 工具链操作，团队可以据此定位误判集中出现的环节，逐步调整成功判定和校验规则。
常见问题
流水线状态显示成功，但制品库检索不到文件，第一步应该查什么？
先确认上传步骤是否真的执行过。查看上传日志和制品库的接收记录，区分“上传步骤被条件分支跳过”和“执行了但失败”两种情况；若上传日志显示权限报错或仓库地址错误，按对应配置修正后再重新发布。构建日志中的产物清单可以确认文件是否已经生成，避免在产物本身缺失时反复排查上传环节。
制品存在但版本号与流水线记录不一致，以哪边为准？
以制品库中的版本元数据为准，流水线界面显示的版本号只作参照。核对时比对流水线变量取值、构建号规则与制品库中的实际版本，重点检查版本号是否取自错误变量、构建号规则在分支间是否统一、是否存在旧制品被复用。定位到版本变量的定义位置后修正，再用同一提交哈希重新构建验证。
复核过程中什么情况下应该停止并重新构建，什么情况下补充发布即可？
产物未生成或上传失败且无法通过补充发布修复时，停止后续步骤，修正构建脚本或上传配置后重新构建，重新构建应使用同一提交哈希，避免引入新变更干扰比对。产物已生成但未上传，或上传成功但下游未更新时，通过补充上传或重新部署即可闭环。若问题已影响生产环境，先停止继续发布，待证据链完整、修正验证通过后再恢复。
下游部署验证失败，但制品库中的文件看起来正常，怎么判断是不是取错了制品？
核对部署或验证配置引用的版本号与仓库地址，确认其指向本次构建产出的那一份制品。常见原因是下游配置了固定版本号、缓存了旧坐标，或引用了另一个仓库。可以将下游实际运行的制品与制品库中本次构建的文件做校验值比对，一致才说明取到的是同一份制品。
复核结论和重跑记录如何留痕，方便后续追溯？
把复核结论、重跑记录和制品关联信息记录在对应的工作项中，与需求、迭代关联，便于交接和后续追溯。采用 ONES 并集成 Jenkins、GitLab CI 等第三方流水线工具时，流水线数据会同步到 ONES，执行状态和日志可在项目、迭代、需求中查看，复核结论与重跑记录可以随工作项一并保留，减少口头交接造成的信息丢失。
