构建缓存失效排查：一次配置改动带来的两小时

先看命中率，再看耗时

构建变慢时，直觉反应是翻代码找热点，但更快的路径是先确认缓存是否还生效。命中率从高位掉到低位，无论代码怎么写，耗时都会显著上升。

多数构建工具都能输出缓存统计。把连续几次构建的命中数、写入数与淘汰数记录下来，对比前后差异，通常能立刻判断问题是否出在缓存层。

哪些输入会进哈希

缓存键一般由源文件内容、依赖版本、编译参数与环境信息共同决定。其中任何一项变化，都会让对应模块失效。问题在于，有些输入并不显眼：构建时间戳、完整路径、临时目录名，甚至本地环境变量。

一台机器正常、另一台不正常的场景，多半与此有关。统一构建环境、把路径相关信息从哈希输入中剔除，是见效较快的调整。

依赖漂移是常见元凶

锁文件未提交、使用范围版本号、或者镜像源返回了不同元数据，都会让依赖树在生产与本地之间产生偏移。表现是本地缓存充足，流水线每次都从头开始。

排查方法是把依赖解析结果导出并做差异比对，而不是凭版本号字符串判断。同一版本号在不同源里指向的产物未必一致。

产物与源码的映射关系

部分工具在缓存中不直接存产物，而是存中间表示。这时源码的小幅改动可能触发大范围重算，因为中间表示的划分粒度与源码模块并不对齐。

调整模块边界、减少跨模块的隐式依赖，可以让失效范围收敛。这属于结构性改动，收益长期但见效慢，需要在迭代中逐步推进。

把缓存当作契约来维护

缓存策略写清楚、纳入评审，比事后排查更省力。新增构建参数时，明确它是否应参与哈希；引入新依赖时，确认版本是否锁定。

同时在流水线里加一道告警：命中率低于阈值即提示。这样问题在引入当天就能被发现，而不是积累到构建时间翻倍后才追溯。