必须启用buildkit并使用type=registry的--cache-from，指向所有节点可读写的统一远程缓存源（如harbor/ecr），配合--cache-to mode=max持续更新，且dockerfile、基础镜像digest、缓存ref须严格一致。
直接用 --cache-from 实现多机缓存共享，关键不是“加个参数就行”，而是让它指向所有节点都能访问的**统一远程缓存源**。本地缓存路径或单机镜像标签无法跨机器生效，必须配合 buildkit 和支持 oci artifacts 的镜像仓库（如 harbor、ecr、docker hub）。
必须启用 BuildKit 并使用 registry 类型缓存
默认 Docker 构建不支持跨节点缓存复用。--cache-from 在旧版引擎中只认本地镜像；只有在 BuildKit 启用后，它才能解析并拉取远程 registry 中存储的缓存元数据。
- 构建前确保环境变量已设：
export DOCKER_BUILDKIT=1 -
--cache-from必须搭配type=registry，例如：--cache-from type=registry,ref=myreg.example.com/myapp:buildcache - 该 ref 对应的镜像仓库需开启 OCI artifacts 支持（Harbor ≥2.0、ECR 默认支持）
缓存源要稳定且可写入
多个 CI 节点共用同一缓存 ref，但不能只读——后续构建需通过 --cache-to 持续更新它。否则缓存会停滞，命中率逐次下降。
- 首次构建时，必须同时指定
--cache-to推送缓存，例如：--cache-to type=registry,ref=myreg.example.com/myapp:buildcache,mode=max -
mode=max表示尽可能导出所有可缓存层（包括中间阶段），提升复用概率 - 所有节点使用完全相同的
ref（含域名、仓库名、tag），避免因命名差异导致“看似共享实则隔离”
Dockerfile 和基础镜像必须保持一致性
缓存命中依赖内容寻址：哪怕一行注释、一个空格、或基础镜像 digest 微调，都会让某层哈希值变化，导致其后所有层重建。
- FROM 镜像推荐用固定 digest（如
FROM ubuntu:22.04@sha256:abc...），而非:latest或:22.04 - COPY/ADD 前尽量先 COPY
go.mod或package-lock.json单独成层，避免源码变更连带重装依赖 - 避免在 Dockerfile 中使用动态 ARG（如
BUILD_TIME），除非显式标记ARG BUILD_TIME --no-cache=true
验证是否真正命中远程缓存
构建日志里不能只看 “Using cache” —— 那可能是本地已有镜像的误判。要确认是否拉取了远程缓存：
- 观察日志中是否有
cache key not found, downloading...或found remote cache类提示 - 执行
docker buildx imagetools inspect myreg.example.com/myapp:buildcache，查看是否包含application/vnd.buildkit.cacheconfig.v0类型的 manifest - 对比两次构建耗时：若第二台机器首次构建时间明显缩短（尤其在依赖下载、编译阶段），说明缓存已生效
