在日常开发与 CI/CD 流水线中，Docker 镜像偶尔从“秒级增量构建”退化为“全量重建”，往往不是缓存功能失效，而是 Dockerfile 指令、构建上下文或缓存存储环境发生了变化。🔍 想要缩短构建时间，关键不是盲目增加缓存，而是定位第一个未命中的步骤，并减少它对后续层的连锁影响。
一、先理解 Docker 构建缓存的链式规则
Docker 会按顺序执行 Dockerfile 指令，并判断当前指令及其依赖内容是否与已有缓存一致。某一层发生变化后，该层以及后续依赖层通常都需要重新执行。因此，越靠前的步骤影响范围越大；高成本、低频变化的步骤应尽量靠前，高频变化的业务代码则应靠后。具体原理可参考 Docker 构建缓存文档。
例如，先执行“COPY . .”，再安装依赖，会导致任意源码、日志或说明文件变化时，依赖安装层也被重新构建。更合理的顺序是先复制依赖清单，完成依赖安装，再复制业务代码。📦
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
二、从第一个缓存未命中点开始排查
排查时应使用普通进度输出观察每一步，而不是只看最终耗时。使用 BuildKit 或 buildx 构建时，可以执行：
docker buildx build --progress=plain --load -t demo:debug .
日志中的“CACHED”表示该步骤复用了缓存；第一个没有出现“CACHED”的步骤通常就是排查入口。不要先关注最后一个慢步骤，因为它可能只是被上游变化连带触发。建议连续执行两次相同命令：如果第二次仍然大量重建，就应检查 Dockerfile、构建参数、基础镜像和构建器是否一致。
常见失效原因清单
- COPY 或 ADD 输入变化：文件内容、权限或参与复制的文件集合发生改变，都可能导致缓存键变化。
- 过早复制整个项目：源码、测试报告、临时文件和本地依赖被一起加入构建上下文。
- 构建参数变化：ARG 的值改变后，使用该参数的步骤及其下游步骤可能重新执行。
- 基础镜像变化：使用浮动标签并拉取到新的镜像内容，会改变后续构建链。
- 构建节点不同：CI 使用临时 Runner，而缓存只保存在上一台机器的本地目录中。
- 主动禁用缓存：构建命令包含 --no-cache，或者流水线定期清理了 BuildKit 缓存。
- 动态内容进入指令：时间戳、随机值、提交号或频繁变化的环境变量被放在 Dockerfile 前部。
三、缩小构建上下文，避免无关文件扰动
.dockerignore 不只是减少上传体积，也能降低无关文件进入 COPY 范围后引发缓存失效的概率。应排除 .git、本地依赖目录、编辑器配置、构建产物、测试覆盖率报告、日志以及临时文件。对于单体仓库，还应将构建上下文限制在真正需要的目录，避免从仓库根目录发送全部内容。
.git
node_modules
dist
coverage
*.log
.env
.idea
.vscode
需要注意的是，不能机械复制忽略规则。若 dist 是镜像运行时所需的预构建产物，就不应排除；若应用确实需要某份配置，也应通过明确的 COPY 或安全的构建参数传入。✅
四、按变化频率重排 Dockerfile
缓存优化的核心策略可以概括为“稳定层在前，易变层在后”。基础系统依赖、编译工具和语言依赖通常变化较少，可以提前处理；源码、静态资源和版本信息变化频繁，适合后置。Docker 官方也建议合理安排层顺序、缩小上下文并使用缓存挂载，详见 缓存使用优化指南。
- 先选择明确、稳定且满足安全要求的基础镜像。
- 安装较少变化的系统软件包。
- 只复制锁文件与依赖描述文件。
- 安装项目依赖。
- 复制业务源码并执行编译。
- 最后写入版本标签或高频变化的元数据。
多阶段构建也能隔离编译环境与运行环境。构建阶段保留编译器和开发依赖，运行阶段只复制最终产物，不仅能减小镜像，也能避免运行镜像受到无关工具链变化的影响。🧱
五、使用 BuildKit 缓存挂载降低重建成本
即便某一层必须重新执行，也不意味着所有依赖都要重新下载。BuildKit 的缓存挂载可以保存包管理器缓存，使 npm、pip、Maven、Go 或 apt 在重新执行时复用已下载内容。它优化的是步骤内部成本，与直接命中镜像层缓存并不完全相同。
RUN --mount=type=cache,target=/root/.npm npm ci
缓存挂载目录应匹配包管理器的实际缓存位置，同时避免把敏感凭据写进缓存层。需要私有仓库认证时，应优先使用 BuildKit secret 挂载，而不是通过 COPY 或普通 ARG 将令牌带入镜像历史。
六、让 CI 环境真正共享缓存
本地构建命中、CI 却每次全量重建，通常说明缓存没有跨任务保存。对于临时构建节点，可以使用 registry、local 或 CI 平台支持的远程缓存后端，并在构建时同时配置 cache-from 与 cache-to。远程缓存的价值在于让不同 Runner、分支和流水线复用结果，而不是依赖某台机器的本地状态。
实践中可让主分支持续导出稳定缓存，功能分支优先读取自身缓存，再回退读取主分支缓存。还要保持 Dockerfile 路径、目标阶段、构建上下文、平台参数和 BuildKit 版本策略一致，否则即使远程缓存存在，也可能因缓存键不同而无法命中。🚀
七、建立可重复的命中率评估方法
优化前后应在相同环境下分别测试四种场景：完全无变化、仅修改业务源码、仅修改依赖锁文件、修改基础镜像或系统依赖。记录总构建时间、每一步耗时、缓存命中步骤以及远程下载时间。不要仅比较一次构建结果，因为网络波动和 Runner 性能差异可能掩盖真实效果。
如果“无变化构建”仍有步骤重新执行，说明构建输入不稳定；如果“仅改源码”触发依赖安装，说明 Dockerfile 顺序需要调整；如果缓存已经命中但整体仍慢，则应继续检查上下文上传、镜像拉取、缓存导入和推送耗时。📊
总结
Docker 构建缓存优化应遵循一条清晰路径：先通过详细日志找到第一个未命中层，再检查其指令、输入文件、构建参数和缓存来源；随后利用依赖文件前置、源码后置、.dockerignore、多阶段构建、缓存挂载和远程缓存减少重复工作。真正稳定的方案不是让所有步骤永远命中，而是让必要变化只影响最小范围，并让无法避免的重建尽可能低成本。
