Docker Buildx 查看多平台构建缓存的操作清单

查看 Docker Buildx 多平台构建缓存，应先确认构建使用的 builder，再分别看“某次构建的缓存命中情况”和“builder 保存的缓存占用”。命令 docker buildx --builder 名称 du --verbose 用于后者；Docker Desktop 的 Builds 详情可按平台查看构建信息。二者不能互相替代，也不能把 builder 的全部占用直接算成某一个平台的缓存大小。

Docker 官方文档：https://docs.docker.com/

Buildx 缓存占用命令：https://docs.docker.com/reference/cli/docker/buildx/du/

下面以“同一项目构建 linux/amd64 与 linux/arm64 后，缓存占用和预期不一致”为例。需要可用的 Docker Engine 和 Buildx；有 Docker Desktop 时可同时使用图形界面。文中的图是原创操作说明图，命令是供读者使用的示例，没有伪造执行输出。

步骤一：确认实际使用的构建器

在 Docker Desktop Dashboard 点击 Settings → Builders。先查看 Selected builder，再对照当时构建命令或 CI 任务是否显式指定了其他 builder。示例名称 multi-demo 必须替换为实际存在的名称。

若要切换默认构建器，在 Available builders 找到目标，展开名称旁的菜单并选择 Use。可见成功状态是 Selected builder 更新为目标名称。切换默认值会影响后续未显式指定 builder 的命令，因此仅做排查时，更推荐在命令中显式指定名称。

# 列出 builder 和节点；名称列的星号表示当前选中的 builder。
docker buildx ls
# 显式指定排查目标，避免误看另一个 builder 的缓存。
docker buildx --builder multi-demo du

对照名称、驱动、节点与端点，而不是只看平台列表。平台列表表示构建能力，不表示这些平台已经产生缓存；CLI 和 Desktop 若连接的 Docker context 不同，也可能看到不同环境。远程 builder 的缓存属于远端存储，不能因为本机磁盘没增长就认为缓存没有保存。

步骤二：按平台查看构建记录的缓存使用

从 Docker Desktop 左侧进入 Builds → Build history，选中要排查的那一次构建，再打开 Info。对于多平台构建，使用 Info 右上角的平台下拉框选择 linux/amd64 或 linux/arm64，对照 Build timing 中的 Cache usage 等信息。

可见确认状态是详情属于目标构建，平台选择已更新，页面展示相应构建信息。不要把另一次源码或参数不同的构建拿来直接比较命中情况。缓存是否可复用还受上下文、Dockerfile 指令、构建参数和基础镜像等输入影响。

如果历史为空，先确认 builder 是否处于运行状态。Docker 官方说明，Builds 列表只显示活动、运行中的 builder 所提供的构建记录；导入别人的构建记录也只是导入查看材料，不意味着把对应缓存搬到了当前 builder。

步骤三：读取该构建器的缓存占用

回到 Settings → Builders，对目标活动 builder 点击展开图标，可查看驱动、支持平台与 Disk usage 等信息。可见确认状态是展开的 builder 名称正确，并且其状态可检查；不要为了看缓存而点击 Remove。

需要逐条看缓存对象时使用以下只读查看命令：

# 展示缓存记录的描述、使用时间以及 mutable、shared 等属性。
docker buildx --builder multi-demo du --verbose

重点读 ID、Description、Last used、Size、Reclaimable 与 Shared。Reclaimable 表示记录的可回收状态，不表示它下一次构建不会再被用到；Shared 表示存储与其他资源共享，因此删除缓存记录后不一定释放相同数量的物理空间。Mutable 记录的内容和容量可能继续变化。

du 的记录字段并不提供一个通用的“平台容量汇总”列。相同构建可能包含平台相关步骤，也有可共享的内容；不能通过数记录、按描述中的平台词过滤，或简单把两个平台容量相加，就得出可靠的总磁盘用量。

缓存看起来异常时怎样判断

BuildKit 的内部缓存和外部缓存要分开。registry、local 等缓存后端把可复用内容导出到其他位置；下次构建还需要正确导入。du 不能代替对远程 registry 缓存对象或本地导出目录的容量管理。排查时记录 builder、构建记录、平台、缓存来源及时间，才方便在同一口径下比较。

这份清单只查看信息，不需要执行 prune。尤其不要把删除 builder 当成“刷新缓存显示”：官方说明，移除使用 docker-container 或 kubernetes 驱动的 builder 会同时移除其构建缓存。

PLATFORMS 同时有 amd64 和 arm64，是否说明两份缓存都完整？

不能。它描述节点支持的平台能力；是否生成和保留某些缓存，需要结合具体构建记录和缓存对象判断。

du 的总量能代表刚刚那次构建新增的缓存吗？

不能直接代表。它是 builder 当前缓存占用视角，可能混有旧构建和共享对象；同时运行的构建与回收也会改变数据。

只切换 builder，旧缓存会自动迁移过来吗？

不会因为选择动作自动迁移。需要复用其他环境的缓存时，应通过支持的缓存导出、导入方式明确配置。

界面入口：https://docs.docker.com/desktop/settings-and-maintenance/settings/。构建详情：https://docs.docker.com/desktop/use-desktop/builds/。外部缓存：https://docs.docker.com/build/cache/backends/。