Docker Buildx 缓存导出到注册表的配置方法

Docker Buildx 要把构建缓存放到注册表，关键不是给最终镜像再加一个标签，而是给缓存单独准备一个 registry 引用。构建时用 --cache-to 导出，用 --cache-from 导入，最终镜像引用和缓存引用保持分离，重复构建才有稳定的复用入口。

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

下面以 registry.example.com/team/demo 为最终镜像，以 registry.example.com/team/demo-buildcache 为缓存镜像。示例中的域名只是占位符，实际使用时替换为团队有推送权限的 OCI 注册表。

一、先分开最终镜像与缓存引用

缓存是构建过程的中间产物，最终镜像是交付产物。二者共用一个引用时，新的缓存写入可能覆盖镜像标签，后续排查也很难分清“可运行镜像”和“构建加速数据”。先固定两个不同的 ref：

最终镜像：registry.example.com/team/demo:latest
构建缓存：registry.example.com/team/demo-buildcache:main

如果流水线有多个分支，可以把 main 替换为经过清洗的分支名，例如 feature-orders。同一个 cache ref 反复写入时，后一次导出会更新该位置，因此不要让多个互不相关的构建同时争用同一标签。

二、设置缓存导出和导入参数

在构建设置中新增一个 registry 缓存出口和一个 registry 缓存入口。真正需要落到 Buildx 命令的最小配置如下：

# 最终镜像与构建缓存使用不同的 registry 引用
docker buildx build \
  --push \
  --tag registry.example.com/team/demo:latest \
  --cache-to type=registry,ref=registry.example.com/team/demo-buildcache:main,mode=max \
  --cache-from type=registry,ref=registry.example.com/team/demo-buildcache:main \
  .

type=registry 表示缓存写入注册表；ref 指向独立的缓存镜像；mode=max 会把中间阶段也纳入导出，适合多阶段 Dockerfile 想提高命中率的场景。若更关心传输时间和存储占用，可以先使用默认的 mode=min，再用实际构建数据决定是否扩大缓存范围。

三、确认构建器与注册表权限

配置写对但缓存仍然没有落地，通常要看两个依赖：当前 builder 是否支持所选缓存后端，以及当前登录身份是否能推送缓存引用。先查看 builder，再登录目标注册表：

# 查看当前构建器和驱动，确认构建环境不是误用的旧配置
docker buildx ls

# 使用有推送权限的账号登录目标注册表；不要把密码写进脚本或文章
docker login registry.example.com

Docker 官方文档说明，默认 docker driver 是否可用 registry 后端还与 containerd image store 配置有关；如果当前环境不满足，应该改用合适的 builder driver，而不是不断修改 cache-to 字符串。注册表权限也要同时覆盖最终镜像和独立的缓存镜像引用。

在图形化构建设置中，可以把这一步理解为“选择构建器”和“选择凭据”两个依赖项：配置面板只负责保存参数，真正推送时仍由 builder 和 registry 会话完成。

四、保存配置并识别结果状态

保存后重新发起一次构建，重点观察两个结果是否分别完成：最终镜像被推送到产品镜像 ref，缓存被导出到 cache ref。不要只看到镜像构建成功就认为缓存也成功。

# 给一次构建设置清晰的标签，便于把输出和缓存引用对应起来
docker buildx build \
  --push \
  --tag registry.example.com/team/demo:2026-10 \
  --cache-to type=registry,ref=registry.example.com/team/demo-buildcache:main,mode=max \
  --cache-from type=registry,ref=registry.example.com/team/demo-buildcache:main \
  .

# 第二次构建仍使用相同 cache ref，让 BuildKit 尝试导入已有缓存
docker buildx build \
  --push \
  --tag registry.example.com/team/demo:2026-10-rerun \
  --cache-from type=registry,ref=registry.example.com/team/demo-buildcache:main \
  --cache-to type=registry,ref=registry.example.com/team/demo-buildcache:main,mode=max \
  .

第一次构建的结果状态应同时出现镜像推送和缓存导出；第二次构建则应看到若干步骤从缓存命中。缓存没有命中不等于构建失败，可能只是 Dockerfile 输入已经变化，或第一次导出尚未成功。

五、按分支隔离，必要时回退缓存

主分支和功能分支最好使用不同的缓存标签，再按需要同时导入主分支缓存。这样既能复用稳定基础层，也不会让每个分支互相覆盖全部中间层：

# 先导入当前分支缓存，再导入主分支的公共缓存
docker buildx build \
  --push \
  --tag registry.example.com/team/demo:feature-orders \
  --cache-from type=registry,ref=registry.example.com/team/demo-buildcache:feature-orders \
  --cache-from type=registry,ref=registry.example.com/team/demo-buildcache:main \
  --cache-to type=registry,ref=registry.example.com/team/demo-buildcache:feature-orders,mode=max \
  .

当 feature-orders 的缓存引用尚不存在时，导入步骤可以失败，但构建仍可继续；这时由导出步骤创建新的分支缓存。真正需要回退时，只保留已知稳定的 main cache-from，暂时去掉问题分支的导入项，避免旧缓存异常影响当前构建。

常见配置误区

• 缓存 ref 和镜像 ref 相同：改成独立的 cache image，避免产物互相覆盖。
• 只写 cache-to 不写 cache-from：第一次能导出，但后续构建没有导入入口。
• 一开始就固定 mode=max：它覆盖的层更多，传输和存储成本也可能更高，应结合多阶段构建收益决定。
• 不同分支共用一个缓存标签：改为分支级 ref，或至少为并行流水线分配稳定的 scope。
• 把构建成功当作缓存成功：分别关注最终镜像推送、缓存导出和下一次缓存命中。

配置速查

相关问题

缓存导入目标不存在会让构建失败吗？通常不会，导入缓存失败时构建仍可继续；但首次构建要保证 cache-to 有推送权限。

什么时候使用 mode=min？最终镜像较简单、缓存传输预算有限时可以先用默认的 min；多阶段中间层复用价值高时再比较 max。

为什么第二次构建仍没有命中？检查 Dockerfile 前置输入、构建参数、分支 cache ref、builder 驱动和注册表权限，先确认第一次确实完成了缓存导出。