构建失败证据：从一条红字追到可复核的根因

构建失败证据链先冻结工具、配置和环境，再沿解析、配置、执行、产物四层收集可复核证据。高清原图

同一条构建命令，开发机成功，CI 却失败。日志最后一行可能只是 Could not resolve、Task failed 或 linker command failed，真正改变结果的输入却藏在更早的位置：另一套工具版本、用户目录中的配置、未提交的生成文件、缓存命中、代理注入，甚至一条只在某个平台成立的路径。

这类问题不能靠截取最后二十行日志解决。可靠的排障过程要回答三个问题：失败发生在哪一层，哪项输入与成功现场不同，修复后能否在干净条件下重复得到相同结果。

先冻结现场，不要急着“清一切”

失败刚发生时，缓存、临时目录和日志仍保留着最有价值的线索。第一轮动作应当只读，避免执行升级依赖、删除 lockfile、全盘清缓存或关闭 TLS 校验。这些动作可能让构建暂时通过，却会抹掉差异来源。

先建立一次取证目录：

$case = "build-evidence/$((Get-Date).ToUniversalTime().ToString('yyyyMMddTHHmmssZ'))"
New-Item -ItemType Directory -Force "$case/logs", "$case/model", "$case/env", "$case/artifact" | Out-Null

git rev-parse HEAD | Set-Content "$case/source-commit.txt"
git status --short | Set-Content "$case/source-status.txt"
git diff --stat | Set-Content "$case/source-diff-stat.txt"

源码状态必须与提交号一起保存。只记录 commit 会漏掉未提交文件，只保存完整 diff 又可能泄露业务代码和凭证。首轮证据用状态与统计确认现场是否干净；确实需要 diff 时，再经过脱敏和访问控制后单独保管。

工具身份不是一行版本号

构建实际使用的入口可能来自 IDE、PATH、Wrapper、版本管理器或容器。至少记录可执行文件位置、版本和 Wrapper 校验材料：

Get-Command node,npm,java,mvn,gradle,dotnet,cmake,ninja -ErrorAction SilentlyContinue |
  Select-Object Name,Source,Version |
  ConvertTo-Json -Depth 3 |
  Set-Content "$case/env/tool-paths.json"

node --version 2>&1 | Set-Content "$case/env/node-version.txt"
java -version 2>&1 | Set-Content "$case/env/java-version.txt"
dotnet --info 2>&1 | Set-Content "$case/env/dotnet-info.txt"
cmake --version 2>&1 | Set-Content "$case/env/cmake-version.txt"
ninja --version 2>&1 | Set-Content "$case/env/ninja-version.txt"

命令不存在不代表可以忽略，反而说明失败可能发生在工具发现阶段。记录“未找到”及 PATH 的脱敏摘要，比临时安装一个最新版更有价值。

环境变量只保存名称和来源

完整环境快照常常包含 token、代理口令、云凭证和内部地址。默认只保留会改变构建行为的变量名，不保留值：

$buildNames = @(
  'CI','PATH','JAVA_HOME','DOTNET_ROOT','NODE_OPTIONS',
  'HTTP_PROXY','HTTPS_PROXY','NO_PROXY','SOURCE_DATE_EPOCH',
  'NPM_CONFIG_USERCONFIG','GRADLE_USER_HOME','MAVEN_OPTS'
)

$buildNames | ForEach-Object {
  [pscustomobject]@{
    Name = $_
    Present = [bool](Get-Item "Env:$_" -ErrorAction SilentlyContinue)
  }
} | ConvertTo-Json | Set-Content "$case/env/environment-presence.json"

若必须比较值，只记录枚举值、布尔值、路径类别或单向摘要。例如把工作目录归一化成 <workspace>，把内部主机替换成 <registry-host>，不要把秘密“打码一半”后继续传播。

四层模型比报错字符串更稳定

构建链路可以压缩成四层：

错误通常在下游显现，却由上游差异触发。链接失败可能是解析到了不同二进制包，测试失败可能是配置阶段启用了不同 profile，产物哈希不同也可能来自时间戳而非源码。

排查顺序固定为：先判断最早出现分歧的层，再追该层的输入。不要从最后一条红字倒推出唯一原因。

解析层：证明“到底解析了什么”

解析层负责把 manifest、lockfile、仓库和平台约束变成依赖图。这里的核心证据不是“依赖安装成功”，而是选中的名称、版本、来源、校验值和冲突决策。

JavaScript 与 Python

npm ls --all --json 2>&1 | Set-Content "$case/model/npm-tree.json"
pnpm list --depth Infinity --json 2>&1 | Set-Content "$case/model/pnpm-tree.json"
yarn info --all --recursive --json 2>&1 | Set-Content "$case/model/yarn-tree.json"

python -m pip inspect --local | Set-Content "$case/model/pip-inspect.json"
uv tree --locked 2>&1 | Set-Content "$case/model/uv-tree.txt"

树太大时不要只截图冲突附近。保留机器可读原件，再生成经过裁剪的阅读副本。比较时重点看直接依赖是否相同、传递版本为何变化、包是否来自批准来源，以及 lockfile 是否被当前工具改写。

Maven：有效 POM 与实际依赖树要成对保存

父 POM、Super POM、profile 和属性插值会共同形成最终模型。pom.xml 看起来一致，并不意味着有效模型一致。Maven 的 POM Reference给出了 help:effective-pom 入口；依赖插件的 dependency:tree输出实际使用的解析树。

./mvnw -B help:effective-pom -Doutput="$case/model/maven-effective-pom.xml"
./mvnw -B help:active-profiles | Set-Content "$case/model/maven-active-profiles.txt"
./mvnw -B dependency:tree `
  -DoutputFile="$case/model/maven-dependency-tree.txt" `
  -Dverbose

有效 POM 可能展开仓库地址、插件配置和属性值。进入工单前应删除认证信息、内部主机和本机绝对路径；原件只放在受控证据库。

Gradle：依赖图、配置选择和任务图分开看

./gradlew projects > "$case/model/gradle-projects.txt"
./gradlew tasks --all > "$case/model/gradle-tasks.txt"
./gradlew :app:dependencies --configuration runtimeClasspath `
  > "$case/model/gradle-runtime-dependencies.txt"
./gradlew :app:dependencyInsight `
  --dependency example-library `
  --configuration runtimeClasspath `
  > "$case/model/gradle-dependency-insight.txt"
./gradlew build --dry-run > "$case/model/gradle-task-plan.txt"

Gradle 的 命令行手册把 dependencies、dependencyInsight、--dry-run 和任务图能力放在不同入口。依赖图回答“选了哪个组件”，任务计划回答“准备执行什么”，不能拿其中一个替代另一个。

Build Scan 是可共享的构建元数据记录，但 --scan 可能把数据发布到外部服务并要求接受服务条款。使用前先确认组织的数据边界；需要留在本地时，优先保存文本报告、--profile 结果或接入自管 Develocity。Gradle 的 Build Scan 文档明确说明了发布位置与采集信息入口。

Gradle 没有与 MSBuild .binlog 等价的通用二进制日志开关。团队手册若把 --scan、--profile 和 .binlog 写成同一种证据，排障人员会高估可重放能力，也可能误把敏感元数据发送出边界。

配置层：把最终生效值还原出来

配置失败最难发现，因为仓库中的配置文件只是输入之一。用户级配置、环境变量、命令行参数、profile、toolchain 与 IDE 注入都可能覆盖它。

配置证据应回答：值从哪里来，最后是什么，为什么覆盖前一层。

通用配置来源表

配置对象	证据	高发误判
工具版本	Wrapper、可执行路径、版本输出	“机器装过”就等于实际使用
依赖来源	effective config、请求主机、lock 来源	仓库配置没写公网就不会访问公网
profile / feature	激活列表、命令行参数、CI 变量名	默认 profile 在所有环境相同
编译器与 SDK	toolchain 输出、target triple、generator	运行时版本等于编译目标版本
代理与 CA	配置来源、证书链、代理层级	浏览器能访问就代表 CLI 能访问
工作目录	入口脚本、当前目录、项目根	IDE 与终端从同一目录启动

MSBuild：预处理模型和 binary log 各有职责

dotnet msbuild src/App/App.csproj `
  -preprocess:"$case/model/msbuild-preprocessed.xml"

dotnet build src/App/App.csproj `
  -bl:"$case/logs/msbuild.binlog;ProjectImports=None" `
  -v:diag `
  *> "$case/logs/msbuild-diagnostic.txt"

预处理项目适合追属性与 import 的最终形态；binary log 保留结构化构建事件，适合追 target、task、输入输出和并行执行。微软的 MSBuild 日志排障说明特别提醒，binary log 可能包含项目文件、导入内容、访问过的环境变量、完整路径和任务参数。

ProjectImports=None 能减少导入文件内容进入日志，但不等于自动脱敏。共享前仍要检查命令行、属性、环境变量、路径和生成代码。含密钥的 .binlog 应按凭证泄漏处理，而不是普通附件。

CMake：先看 cache，再看 trace

cmake -S . -B build/evidence -G Ninja `
  --log-level=VERBOSE `
  2>&1 | Tee-Object "$case/logs/cmake-configure.txt"

cmake -S . -B build/evidence -G Ninja `
  --trace-expand `
  --trace-redirect="$case/logs/cmake-trace.txt"

cmake -LAH -N build/evidence | Set-Content "$case/model/cmake-cache-summary.txt"

CMakeCache.txt 说明已经选择的编译器、路径和 feature；--trace-expand 说明变量展开后哪些命令实际执行。trace 通常非常大，还可能包含路径和参数，只有在普通配置日志无法解释覆盖关系时才开启。具体开关以 cmake 命令行手册为准。

执行层：确认“计划执行”和“实际执行”

依赖与配置一致，仍可能因为任务顺序、增量判断、并发、外部进程或工作目录而失败。执行证据至少包含任务图、实际命令、退出码、首个失败节点和其前置节点。

Ninja：命令数据库比终端滚屏可靠

ninja -C build/evidence -t targets all `
  > "$case/model/ninja-targets.txt"
ninja -C build/evidence -t commands app `
  > "$case/model/ninja-app-commands.txt"
ninja -C build/evidence -d explain app `
  *> "$case/logs/ninja-explain.txt"

-t commands 展开目标实际关联的命令，-d explain 解释为什么某个输出需要重建。可用工具及参数应以当前版本的 Ninja Manual为准，先执行 ninja -t list 确认能力，避免在旧版本上套用新参数。

并行构建的最后一条失败不一定是最早根因。临时改成单并发可以改善日志顺序，但只能作为诊断对照：

ninja -C build/evidence -j 1 -v *> "$case/logs/ninja-serial.txt"

如果单并发成功、并发失败，调查共享临时文件、未声明依赖、输出冲突和非线程安全生成器；不要把 -j 1 永久写进权威构建命令掩盖竞态。

每条命令都要保留退出码

& ./scripts/build.ps1 *>&1 |
  Tee-Object "$case/logs/authoritative-build.txt"
$exitCode = $LASTEXITCODE

[pscustomobject]@{
  ExitCode = $exitCode
  FinishedAtUtc = (Get-Date).ToUniversalTime().ToString('o')
} | ConvertTo-Json | Set-Content "$case/logs/result.json"

exit $exitCode

日志采集脚本不能吞掉原命令退出码。很多“本地通过、CI 失败”其实是本地封装脚本总返回 0，开发者只看到了滚屏中的红字，没有把失败交给调用方。

产物层：成功退出不等于得到同一个东西

构建命令返回 0 后，还要证明输出存在、类型正确、内容可用且身份稳定。

$artifacts = Get-ChildItem dist -File -Recurse
$artifacts | ForEach-Object {
  [pscustomobject]@{
    Path = $_.FullName.Replace((Get-Location).Path, '<workspace>')
    Length = $_.Length
    Sha256 = (Get-FileHash $_.FullName -Algorithm SHA256).Hash
  }
} | ConvertTo-Json -Depth 3 | Set-Content "$case/artifact/manifest.json"

哈希不同先判断差异类别：

文件集合不同：任务图、条件编译或生成步骤发生变化。大小相近但哈希不同：时间戳、绝对路径、压缩顺序或签名可能进入产物。只有元数据不同：归档时间、文件权限、所有者、locale 或换行符可能漂移。

二进制逻辑不同：编译器、链接器、优化参数、SDK 或原生依赖可能不同。

需要稳定时间输入时，可评估 SOURCE_DATE_EPOCH；但设置一个变量不会自动让所有工具可复现。还要逐项确认归档器、代码生成器、编译器和签名步骤是否消费它。

产物身份至少包括源码提交、构建合同版本、工具链摘要、依赖锁摘要、目标平台、测试结果和文件哈希。只上传一个同名 ZIP，后续无法证明它来自哪次构建。

从完整项目缩成最小复现

最小复现不是删到“偶尔不报错”，而是保留触发失败所需的最小输入，并能稳定重放。

按下面顺序缩减，每次只改变一个维度：

固定源码提交、工具版本、命令和目标平台。关闭与故障无关的模块，但不改依赖版本和关键配置。用同一来源恢复冷缓存，再运行权威命令。

删除不影响失败的业务代码、测试数据和生成目标。把内部依赖替换成可公开的等价占位对象，确认故障仍存在。在第二台干净机器或受控容器中重放。

每次缩减都记录“改了什么、失败是否仍在、证据哈希是什么”。如果同时升级插件、清缓存、换 JDK 和改配置，即使成功也无法知道哪个动作修复了问题。

一个可交付的复现包

repro/
  README.md                  # 一条权威命令、预期失败和实际失败
  source/                    # 最小源码，不含业务秘密
  wrapper/                   # 工具入口和校验材料
  manifests/                 # manifest、lock、无秘密配置
  evidence/
    tool-identity.json
    effective-model/
    dependency-graph/
    task-graph/
    logs/
    artifact-manifest.json
  checksums.sha256

README.md 只说明重放动作和判断标准，不夹带排障故事。完整时间线、人员和内部链接留在受控工单。

脱敏不是把 token 替换成星号

构建证据中的敏感信息比常规应用日志更密集：

命令行可能包含仓库用户名、签名口令和临时 token。URL 可能在 userinfo 或 query 中携带凭证。effective config 会展开用户目录、私有仓库和代理。

.binlog、Build Scan、trace 会捕获环境变量、项目文件和任务参数。依赖图会暴露内部组件名、版本和系统边界。绝对路径可能暴露用户名、客户名和目录结构。

建立两份材料：原始证据进入受控存储，阅读副本经过规则化脱敏。脱敏脚本至少扫描常见 token 形态、URL userinfo、认证头、私钥标记、内部域名和绝对路径；随后由人复核上下文。

rg -n -i `
  '(authorization:|bearer\s+|_authToken|password\s*[=:]|secret\s*[=:]|BEGIN .*PRIVATE KEY|https?://[^/\s]+@)' `
  $case

扫描零命中只是底线。内部包名、客户标识、源码片段和构建参数不一定符合 secret 正则，仍可能属于受限数据。

证据保全要能证明没有被悄悄改过

Get-ChildItem $case -File -Recurse |
  Where-Object { $_.Name -ne 'checksums.sha256' } |
  Sort-Object FullName |
  ForEach-Object {
    $hash = (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
    $path = $_.FullName.Substring((Resolve-Path $case).Path.Length + 1).Replace('\','/')
    "$hash  $path"
  } | Set-Content "$case/checksums.sha256"

证据包需要 case ID、采集时间、采集命令版本、访问级别、保留期限和责任人。原件设为只读，修订后的脱敏副本使用新哈希，不覆盖原件。涉及安全事件时，按组织取证流程保留访问记录和交接链。

日志保留越久，泄露面越大；保留太短，又无法复盘间歇故障。普通构建失败与安全事件应使用不同保留策略，不要把所有 .binlog 永久上传到公共工单。

什么时候应该停止继续采集

诊断能力越强，采集成本和数据风险越高。满足下面任一条件时先停下来复核：

已定位到最早分歧输入，现有证据足以构造单变量实验。下一步需要输出明文凭证、业务源码或不受控的环境快照。采集会连接生产源、执行发布脚本或改变共享缓存。

日志体积持续增长，但没有新增能够区分假设的信息。工具升级后错误消失，却还没有在旧版本上保存可重放证据。故障可能涉及供应链攻击、凭证泄漏或制品篡改，需要转交安全响应。

“多收日志”不是默认正确。证据的价值取决于能否排除一个具体假设，而不是文件大小。

修复后按相反方向再验证

修复完成后，不要只在原来的热缓存现场重跑一次。按证据链反向验证：

原失败现场使用相同输入重放，确认错误稳定消失。清理项目级输出，在保留依赖缓存的条件下运行，排除脏产物。使用冷缓存或隔离缓存运行，排除历史缓存掩盖问题。

在 CI 干净环境运行同一权威命令，比较工具、图、任务和退出码。对产物生成清单和哈希，执行约定测试。恢复网络限制、TLS 校验、脚本准入和最小权限，确认修复没有降低安全基线。

最后把根因写成“输入差异 -> 机制 -> 失败现象 -> 修复 -> 防复发检查”，不要只记录“清缓存后恢复”。前者能进入团队知识库，后者会让下一次故障重新从零开始。

团队把取证能力做成日常入口

成熟团队不会等到故障发生才临时拼命令。项目应提供一个只读诊断入口，例如：

./scripts/build-diagnose.ps1 -Output build-evidence -RedactionPolicy standard

这个入口应当具备以下约束：

默认不连接生产、不发布、不修改 lockfile、不清共享缓存。记录工具身份、配置来源、依赖图、任务图、退出码和产物清单。原始材料与脱敏副本分开，输出前运行敏感信息扫描。

支持按生态启用高风险证据，例如 MSBuild binlog、Gradle Build Scan、CMake trace。每个高风险开关显示采集内容、发送位置和保留策略。脚本自身有版本，证据包记录该版本和规则摘要。

故障证据的最终目标不是证明“某个人机器有问题”，而是把不可见差异变成团队可以复核的事实。只要构建仍依赖口头描述、截图和个人缓存，排障速度就取决于运气；当四层证据可以重复采集、脱敏和比较，失败才真正进入工程治理。