Docker buildx 构建多平台镜像时如何查看目标架构

Docker buildx 构建多平台镜像时，不能只看当前电脑是 amd64 还是 arm64。真正要核对的是三层：命令里的 --platform 是“想构建什么”，builder 的 Platforms 是“当前构建器能处理什么”，推送后的 manifest 列表才是“仓库里实际有什么”。

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

先把目标架构写进 buildx 命令

以一个需要同时服务 x86 服务器和 ARM 云主机的镜像为例，可以把目标平台写在构建命令里。软件教程里最容易漏掉的是输出方式：多平台结果通常要推到仓库，不能把两个平台的结果都当成一个本地 Docker 镜像加载。

# 显式声明两个目标平台，并把多平台结果推送到镜像仓库
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/team/sample-api:release \
  --push .

图中的平台选择是操作示意，不是本机运行截图。继续前先看命令是否包含完整的 OS/架构组合；如果只写 --platform linux/amd64，后面看到单个平台 manifest 是正常结果。

用 inspect 确认 builder 是否具备目标平台

参数写对不代表当前 builder 已经具备对应能力。先查看 builder 节点，--bootstrap 会确保构建器启动后再展示状态：

# 启动并查看当前 builder 的节点与平台能力
docker buildx inspect --bootstrap

重点看输出中的 Platforms。它应覆盖命令里的目标组合，例如 linux/amd64 和 linux/arm64。如果只出现一个平台，先检查 builder 驱动、节点配置或是否选错了 builder；不要急着修改 Dockerfile。

用 imagetools inspect 验收仓库里的平台清单

构建命令完成后，检查仓库中的镜像标签，而不是只查看本地缓存。这个命令读取注册表里的镜像详情：

# 查看仓库标签下的 manifest 列表
docker buildx imagetools inspect registry.example.com/team/sample-api:release

输出里的 Manifests 应该有两条平台记录，分别指向 linux/amd64 与 linux/arm64，每条通常还带有独立 digest。这样才说明同一个标签能根据拉取端架构选择对应镜像。

只显示一个平台时按三层边界排查

1. 命令层：确认 --platform 不是单值，也没有被脚本或环境变量覆盖。
2. builder 层：重新运行 docker buildx inspect --bootstrap，对照 Platforms 是否包含目标。
3. 仓库层：确认使用了 --push，并且检查的是刚刚推送的完整标签，而不是旧缓存或另一个 tag。

如果只是想在本地验证某一个架构，可以临时使用 --load，但它不等于已经生成可供多个架构拉取的仓库 manifest。发布前仍应回到 --push 加 imagetools inspect 这条验收链。

常见问题

为什么本机是 ARM，却能构建 linux/amd64？

buildx 的目标平台和宿主机平台不是同一个概念。能否完成还取决于 builder 的节点、仿真或原生构建能力，最终以 builder 状态和构建结果为准。

buildx inspect 与 imagetools inspect 有什么区别？

前者看本地或选定 builder 的能力，后者看注册表中某个镜像引用已经保存的 manifest；一个是构建前检查，一个是发布后验收。

为什么 build 成功但仓库只有一个架构？

常见原因是目标本来只写了一个平台、检查了旧标签，或没有把多平台结果通过 --push 写入仓库。按命令、builder、manifest 三层顺序重查即可。