第1章 CI/CD缓存一致性问题概述
在持续集成/持续交付（CI/CD）流水线中，缓存一致性是决定构建速度与结果可靠性的核心瓶颈。缓存本应加速重复构建，但一旦失效、冲突或产生差异性，就会导致“加速变减速、正确变错误”。本章从三种典型问题出发，梳理缓存不一致的根源、表现形式与排查方向。
1.1 缓存失效
缓存失效指缓存项的生命周期与实际依赖内容不匹配。常见原因有：
- TTL过期策略：定时清理缓存后，后续构建可能因缓存缺失而重新拉取全量依赖。
- 依赖文件变更：
package-lock.json、Gemfile.lock等锁文件未加入缓存 key，导致旧缓存仍然命中。 - 构建环境漂移：代理、镜像源或系统库版本更新后，旧缓存中的预编译产物失效。
典型场景：项目中
node_modules 缓存 key 仅使用分支名，当 master 分支合并了依赖更新后，其他 feature 分支仍沿用旧缓存，导致编译错误。
1.2 缓存冲突
缓存冲突指多个构建流水线同时读写同一缓存键，造成竞态或覆盖。多发生在共享存储（如 NFS、S3、Redis）或多项目复用缓存的场景。
| 冲突类型 | 触发条件 | 典型后果 |
|---|---|---|
| 写入覆盖 | 并行构建向同一 key 写入增量缓存 | 部分缓存损坏，后续构建拿到的产物不完整 |
| 读取不一致 | 一个构建写入一半时被另一个构建读取 | 解压失败或加载异常 |
| 锁竞争 | 使用分布式锁但未考虑超时/重入 | 构建队列长时间阻塞 |
常见误区：在 GitLab CI 中为多个 job 使用相同的
cache:key 且未指定 policy:pull-push，会导致共享缓存被频繁覆盖。
1.3 构建差异性
构建差异性是指相同源代码在不同环境或时间点因缓存不一致产生不同构建结果。这是“不可复现构建”的根源之一。
- 可重入差异：缓存中混入了本地临时文件或路径。
- 增量编译差异：Makefile 或 Gradle 增量编译缓存被破坏后，部分模块未被重新编译。
- 层叠缓存：Docker 构建缓存层被错误复用，导致基础镜像版本上飘。
调试建议：在后续章节中将演示如何通过
cache-clear 脚本与哈希校验快速定位差异性来源。
问题对比概览
| 维度 | 缓存失效 | 缓存冲突 | 构建差异性 |
|---|---|---|---|
| 根因 | key 与内容无关 | 并发写入/读取 | 缓存不幂等 |
| 影响范围 | 性能、正确性 | 稳定性、正确性 | 可重现性、审计合规 |
| 修复方向 | 哈希化、版本化 | 租约、分片、锁 | 隔离、全量校验 |
下面通过一个内联流程示意图，直观展示缓存不一致如何破坏 CI/CD 流水线的预期行为。
调试与初步修复示例
以下是一段 GitLab CI 配置片段，展示了不正确的缓存 key 导致一致性问题的典型写法，以及对应的修复要点：
# 不推荐的写法：仅依赖分支名
cache:
key: "$CI_COMMIT_REF_NAME"
paths:
- node_modules/
# 推荐写法：包含锁文件哈希
cache:
key: "$CI_COMMIT_REF_NAME-${CI_COMMIT_SHA:0:8}"
paths:
- node_modules/
when: on_success
关键优化：在流水线中增加
checksum 步骤，将依赖锁定文件的 MD5 注入缓存 key，即可避免绝大多数缓存失效问题。