在日常开发和 CI/CD 流程中，Docker 镜像构建经常要重复下载依赖、编译源码和生成中间文件。项目规模增大后，即使只修改一行代码，也可能触发多个步骤重新执行。BuildKit 通过更高效的依赖分析、并行处理和缓存导入导出机制，能够显著减少重复工作。本文将从缓存原理、Dockerfile 优化、本地缓存和远程缓存等方面，介绍一套可直接落地的加速方案。🚀
一、确认 BuildKit 构建环境
BuildKit 是 Docker 的现代构建后端。开始配置前，可先执行以下命令检查 Buildx 是否可用：
docker buildx version
docker buildx ls
如果当前环境已经提供可用的 builder，可以直接构建；如果需要独立且功能更完整的构建实例，可执行：
docker buildx create --name fast-builder --driver docker-container --use
docker buildx inspect --bootstrap
使用 docker-container 驱动时，BuildKit 在独立容器内运行，更适合多平台构建以及 registry、local 等外部缓存场景。普通本地项目也可以继续使用默认 builder，但应先确认所需缓存后端是否受到当前驱动支持。相关差异可参考 Docker 构建驱动文档。
二、理解缓存失效规则
Dockerfile 中的指令会形成相互依赖的构建步骤。当某一步的输入发生变化时，该步骤及其后续依赖步骤可能需要重新执行。例如，先复制全部源码，再安装依赖，会导致任何源码变更都可能让依赖安装层失效。Docker 官方对缓存工作方式和失效规则提供了详细说明，参见 构建缓存文档。citeturn1search1
优化的核心原则是：把变化少、耗时长的步骤放在前面，把变化频繁的文件放在后面。以 Node.js 项目为例，可先复制 package.json 和锁文件，执行依赖安装，再复制业务源码；Python 项目可先复制 requirements.txt，安装依赖后再复制应用代码；Maven 项目则可以优先复制 pom.xml 并准备依赖。
推荐的 Dockerfile 分层思路
- 选择并固定合适的基础镜像。
- 设置工作目录和系统级环境参数。
- 复制依赖清单与锁文件。
- 安装项目依赖。
- 复制业务源码并执行编译。
- 使用多阶段构建生成精简的运行镜像。
基础镜像标签也会影响缓存。如果使用持续变化的标签，远端镜像更新后可能产生新的输入摘要。对于强调可重复构建的环境，可以使用明确版本，必要时进一步固定镜像摘要，同时建立定期升级和安全修复流程。🔧
三、缩小构建上下文
执行 docker build 时，当前目录通常会作为构建上下文交给 BuildKit。若其中包含 node_modules、target、dist、测试报告、日志、编辑器配置或 Git 历史，不仅会增加上下文处理成本，还可能因为无关文件变化造成缓存失效。
建议维护 .dockerignore，常见排除项包括：
.git
node_modules
dist
target
*.log
.idea
.vscode
coverage
排除规则应根据项目实际情况调整，不能把构建必需的依赖清单、源码或配置文件误排除。优化后可使用 docker buildx build --progress=plain . 查看各阶段日志，并观察构建上下文大小以及步骤是否显示 CACHED。📦
四、使用缓存挂载保存依赖
镜像层缓存要求整个构建步骤满足复用条件，而缓存挂载可以在步骤必须重新执行时，继续保留包管理器下载的数据。其基本写法是：
RUN --mount=type=cache,target=/缓存目录 构建命令
例如，Python 可将目标目录设置为 /root/.cache/pip，Maven 可使用 /root/.m2，Go 可分别缓存 /go/pkg/mod 和 /root/.cache/go-build，Debian 或 Ubuntu 软件包管理器则可根据构建需求缓存 apt 相关目录。这样即使安装命令重新运行，也有机会直接使用已下载的数据，而不必每次从网络重新获取。
缓存挂载的内容主要服务于构建过程，不会自动复制到最终镜像，因此不应把应用运行所需文件只保存在缓存目录中。对于不适合并发写入的工具，可以配置 sharing=locked，避免多个并行构建同时修改同一缓存。更完整的参数说明可查看 来源链接 缓存挂载说明。
五、为本地构建导入和导出缓存
如果构建节点可能被重建，或者希望在不同工作目录之间共享缓存，可以使用 local 后端：
docker buildx build --cache-from type=local,src=.build-cache --cache-to type=local,dest=.build-cache-new,mode=max -t demo:latest --load .
构建完成后，可用新的缓存目录替换旧目录。将读取目录和写入目录分开，可以避免同一次操作直接覆盖正在使用的缓存。缓存目录通常不应提交到 Git，也需要设置容量清理策略，防止持续积累占满磁盘。
六、在 CI/CD 中配置远程缓存
临时 CI Runner 往往不会保留本地磁盘，因此仅依赖 BuildKit 内部缓存，下一次任务可能无法复用。此时可以把缓存导出到镜像仓库：
docker buildx build --push -t registry.example.com/team/app:latest --cache-from type=registry,ref=registry.example.com/team/app:buildcache --cache-to type=registry,ref=registry.example.com/team/app:buildcache,mode=max .
registry 缓存与最终镜像可以使用不同引用，便于独立管理。BuildKit 还支持 inline、local、registry 和 gha 等缓存后端，具体可用范围与 builder 驱动及镜像存储配置有关。外部缓存需要通过 --cache-to 显式导出，并通过 --cache-from 显式导入，详见 缓存后端官方文档。citeturn1search2
多分支流水线可以同时读取当前分支缓存和主分支缓存，同时为不同分支设置独立写入位置。不要让多个不同范围的构建无规则地覆盖同一个缓存引用，否则缓存命中率和可维护性都会下降。
七、避免常见配置误区
- 每次都使用 --no-cache：该选项适合排查缓存问题或执行明确要求全量刷新的任务，不应作为默认构建方式。
- 过早复制全部源码：应先复制依赖描述文件，完成依赖安装后再复制频繁变化的业务文件。
- 缓存密钥过于宽泛：不同架构、工具链版本和主要分支最好采用可区分的缓存范围。
- 把密钥写入镜像层：认证信息应通过 BuildKit 的 secret 或 SSH 挂载传入，不要使用 COPY 或普通 ARG 固化敏感内容。🔐
- 只看总耗时：应使用 --progress=plain 分析具体步骤，区分缓存未命中、网络缓慢和编译耗时。
总结
BuildKit 缓存加速不是简单增加一个参数，而是对构建输入、Dockerfile 顺序、依赖目录和 CI 缓存生命周期进行整体设计。建议依次完成四项优化：先精简构建上下文，再调整 Dockerfile 分层，然后为包管理器配置缓存挂载，最后在 CI/CD 中启用 registry、local 或平台专用远程缓存。通过构建日志持续检查 CACHED 状态、耗时步骤和缓存容量，才能让加速效果长期稳定，而不是只在单次构建中偶然生效。✅
