内联缓存的原理
BUILDKIT_INLINE_CACHE=1 让构建把缓存元数据写进镜像本身：推送后的镜像既是产物也是缓存来源，后续构建用 --cache-from 指向同一镜像即可复用其中的层。好处是不需要单独维护缓存镜像或缓存路径，代价是缓存范围只限于镜像自身包含的层，多阶段构建的中间阶段不在其中。
基本信息
| 用途 | 把缓存元数据内联进镜像 |
|---|---|
| 用法 | --build-arg BUILDKIT_INLINE_CACHE=1 配合 --cache-from 镜像 |
| 优点 | 相比独立缓存标签更省管理成本 |
| 限制 | 只覆盖镜像本身的层，中间阶段不可复用 |
| 依赖 | BuildKit / Buildx |
典型使用场景
- CI 构建机器无状态，需要从远端镜像恢复缓存
- 层结构简单的项目，追求最低的缓存维护成本
- 最终阶段就是主要构建成本的项目
- 缓存镜像与发布镜像共用同一个标签，减少额外仓库路径
- 排查缓存未命中时对比镜像元数据
启用与验证
启用与验证
docker pull registry.example.com/app/web:1.0 # 先取得作为缓存来源的镜像
docker buildx build --build-arg BUILDKIT_INLINE_CACHE=1 --cache-from registry.example.com/app/web:1.0 --push -t registry.example.com/app/web:1.0 .
docker buildx imagetools inspect registry.example.com/app/web:1.0 # 确认缓存元数据存在
docker buildx build --cache-from registry.example.com/app/web:1.0 -t app/web:test . # 验证命中情况缓存机制对比
| 机制 | 覆盖范围 | 说明 |
|---|---|---|
| 内联缓存 | 镜像自身的层 | 中间阶段不在其内 |
| registry 缓存后端 | 全部阶段含中间层 | 缓存更完整，配置也更复杂 |
| 本地层缓存 | 本机构建历史 | 换机器即失效 |
| --cache-from 多来源 | 可指定多个 | 按顺序尝试匹配 |
多阶段项目通常配合 registry 缓存后端（--cache-to 与 --cache-from 指向缓存路径）更划算，内联缓存更适合层结构简单、镜像本身就是主要缓存来源的场景。
缓存要前进依赖推送成功：忘记推送新镜像时，下次构建仍会拿旧镜像当缓存来源，看起来像缓存长期不更新。
缓存有效性还取决于 Dockerfile 指令顺序：把变化频繁的步骤（如复制源码）放在安装依赖之后，命中率才高。