Docker buildx 怎样利用缓存缩短镜像构建

Docker buildx 的外部缓存解决的是一个很具体的问题：CI 每次都是干净环境，Dockerfile 前面的依赖安装层反复执行，镜像构建时间越来越长。配置 --cache-to 导出缓存，再用 --cache-from 导入缓存，后续构建就能复用已经计算过的层。这里以 registry 后端为例，重点看缓存位置、命中结果和异常回退。

官方地址：https://docs.docker.com/build/cache/backends/

先准备一个独立的缓存镜像引用，再让每次构建同时“导入旧缓存、导出新缓存”。缓存位置不能被多个分支无意覆盖，首次构建没有命中也属于正常现象。

先选对缓存位置和后端

BuildKit 自带本地内部缓存，但 CI 运行器经常在任务结束后被回收，因此需要把缓存导出到外部位置。registry 后端会把缓存写入一个独立的镜像引用；它不等于最终业务镜像，建议使用单独的名称，例如 demo-app:buildcache-main。

如果按分支分别维护缓存，可以使用不同的引用，例如主分支使用 buildcache-main，特性分支使用 buildcache-feature-a。不要让多个并发构建同时把不同结果写入同一个缓存位置，否则后写入的内容可能覆盖先前数据。

把导入和导出放进同一次构建

下面的命令把最终镜像推送到仓库，同时把构建缓存推送到独立引用，并从主分支缓存读取已有层。代码中的仓库地址和镜像名都是占位符，替换成自己的仓库即可。

# 导入主分支缓存，并把本次结果导出到当前分支缓存
docker buildx build \
  --push \
  --tag registry.example.com/team/demo-app:feature-a \
  --cache-from type=registry,ref=registry.example.com/team/demo-app:buildcache-main \
  --cache-to type=registry,ref=registry.example.com/team/demo-app:buildcache-feature-a,mode=max \
  .

--cache-from 负责读取，--cache-to 负责写入；二者不能只配置一边。mode=max 会把中间步骤也纳入导出缓存，通常更容易命中，但缓存体积和导入导出开销也会增加。

如果构建目标只需要最终镜像中已经导出的层，可以先使用默认的 mode=min。当 Dockerfile 的中间阶段很重、而 CI 需要复用这些阶段时，再把导出模式调整为 max。

从构建结果核对缓存是否生效

缓存是否“生效”不能只看命令成功。第一次构建通常没有可用的远端缓存，重点是确认它完成了导出；第二次或后续构建才观察哪些步骤被复用。建议在 CI 日志中同时记录目标镜像、缓存引用和构建结果。

可以用下面的检查表判断结果：

• 首次构建：日志允许显示没有命中，但应能看到缓存导出目标。
• 再次构建：依赖安装等稳定步骤应出现缓存复用迹象，构建耗时通常会下降。
• 分支构建：当前分支有自己的导出引用，同时能从主分支读取公共基础层。
• 缓存不可用：构建仍应能回退为正常构建，不能把远端缓存当作唯一产物来源。

几个容易误判的情况

缓存引用被多个分支共用：先拆分引用，再重新构建。不同分支可以共享一个只读的主分支缓存，但不要把所有新缓存都写回同一个位置。

把 cache-to 当成最终镜像输出：它只保存构建缓存，最终镜像仍需通过 --push 或其他输出方式发布。

把首次无命中当成配置失败：首次构建本来就可能没有远端缓存。先检查是否产生了缓存导出，再用同一引用启动第二次构建。

为了命中而长期固定 mode=max：中间层越多，缓存越大。根据 Dockerfile 的阶段结构和 CI 运行成本选择，不要把最大缓存范围当作默认答案。

小结

Docker buildx 缓存的关键不是增加一条参数，而是建立稳定的读写闭环：--cache-from 读取已有缓存，--cache-to 写入独立位置，分支之间用不同引用隔离，再用第二次构建的命中结果核对配置。这样既能缩短重复构建，也不会把缓存误当成最终镜像或唯一依赖。

相关问题

问：为什么第一次构建没有缓存命中？
答：远端缓存还没有生成，或者当前 Dockerfile 与已导出的层不匹配。先确认第一次构建完成导出，再进行第二次构建。

问：主分支和特性分支能不能共用缓存？
答：可以从主分支缓存读取作为公共基础，但建议把特性分支的新缓存写入自己的独立引用，减少并发覆盖。