别把缓存当运气：用三层校验给 Docker 构建提速

Docker 构建变慢后，很多团队的第一反应是“把缓存打开”。但缓存不是开关，而是一项需要验证的工程优化：命中率提高不代表依赖被正确更新，构建变快也不代表产物仍然可信。更稳妥的做法，是把缓存拆成输入、复用和产物三层检查。

第一层：先让输入稳定

如果依赖清单和源码总是一起变化，后面的缓存层自然无法复用。以 Node.js 项目为例，可以把依赖安装与业务代码构建拆开，并只给包管理器缓存挂载：

# syntax=docker/dockerfile:1.7
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,id=npm-cache,target=/root/.npm \
    npm ci

FROM deps AS build
COPY . .
RUN npm run build

同时用 .dockerignore 排除 .git、测试报告、本地日志和构建目录。判断标准很简单：只改 README 时，依赖安装层应当复用；只改 package-lock.json 时，依赖层必须失效。可以用 docker buildx build --progress=plain . 观察每一步是否出现 CACHED，不要只看总耗时。

第二层：确认缓存确实被复用

“磁盘里有缓存”和“本次构建用了缓存”是两件事。建议在 CI 日志里固定记录三个信息：基础镜像版本、Dockerfile 内容哈希、依赖清单哈希。基础镜像如果使用 latest，即使文件没变，重建时也可能拉到最后层，造成结果漂移。生产分支应尽量使用明确版本或镜像摘要。

还可以保留一次冷构建作为基线，再执行一次热构建。比较两者的日志和耗时时，要区分真正复用的层，与因为命令顺序变化而偶然命中的层。缓存目录建议使用稳定的 id，但不要不加区分地在不同架构、不同分支之间共享同一构建输出。

第三层：验证产物，而不是验证速度

缓存命中只是过程指标，最终还要检查产物。一个可执行的流水线至少应包含：构建镜像、在干净容器内运行冒烟测试、记录镜像摘要。例如：

IMAGE=example/app:${GIT_SHA}
docker buildx build --load -t "$IMAGE" .
docker run --rm "$IMAGE" npm test
docker image inspect "$IMAGE" --format '{{.Id}}'

如果热构建与冷构建产出的关键文件哈希不同，应先检查输入是否真的相同，再检查缓存范围是否过大。若测试只能在缓存构建中通过，说明问题很可能藏在未声明的环境变量、时间戳或下载依赖里。

落地建议

1. 依赖安装层与源码构建层分离，缩小失效范围。
2. 在 CI 中打印缓存命中日志，并固定基础镜像版本。
3. 每次发布都执行一次干净环境和缓存环境的产物核对。

缓存的价值不是让错误更快通过，而是让正确的构建稳定地更快完成。把“命中率、可复现性、产物验证”一起纳入流水线，Docker 提速才不是碰运气。