Docker Buildx 怎样把多平台镜像一次推送到仓库

我在把同一个服务交付给 x86 服务器和 ARM 开发板时，最容易踩的坑不是 Dockerfile 写错，而是只构建了当前机器的平台。Docker Buildx 的多平台写法是：用 --platform 一次列出目标平台，用完整镜像标签指定仓库，再用 --push 让 BuildKit 将各平台结果和统一的 manifest list 一起写入 registry。

官方地址：https://docs.docker.com/build/building/multi-platform/

先记住一个判断：多平台构建的产物不是一个“同时适配所有 CPU 的单一镜像”，而是一个镜像索引。索引下面挂着 linux/amd64、linux/arm64 等平台 manifest；用户拉取同一个标签时，Docker 再按主机平台选择对应变体。

先把镜像索引和平台 manifest 分开理解

单平台镜像通常只有一个 manifest，里面记录配置和层。多平台镜像则多了一层 manifest list，也常被称为 image index：它把不同平台的 manifest 组织到同一个标签下面。这样做的价值是交付标签保持一致，消费端不需要手动改成不同架构的标签。

先确认 builder 能不能覆盖目标平台

命令本身可以列出多个平台，但真正执行 Dockerfile 中的 RUN 时，builder 还要能运行或交叉编译这些目标。Docker Desktop 通常已经准备了常见的仿真支持；独立 Docker Engine 则要根据环境准备 QEMU、原生多节点或语言级交叉编译。

# 查看当前 builder 的节点、驱动和可用平台
docker buildx inspect --bootstrap

# 创建一个使用 docker-container 驱动的 builder，并切换到它
docker buildx create --name multiarch --driver docker-container --use
docker buildx inspect --bootstrap

如果输出的 Platforms 没有目标架构，不要急着把问题归咎于镜像仓库。先决定路线：Dockerfile 里有大量与目标架构相关的原生编译时，优先考虑交叉编译或原生多节点；只是运行基础镜像里的常规命令时，仿真通常更直接，但构建速度可能较慢。

用 --platform 和 --push 一次发布两个平台

下面的命令把两个平台写在同一个 --platform 参数里。-t 的值必须是仓库中可推送的完整引用；--push 等价于使用 registry exporter，不会把多平台结果当作普通单平台镜像加载到本地 Docker Engine。

# 同时构建 amd64 与 arm64，并把 manifest list 推送到仓库
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag registry.example.com/team/demo:1.0 \
  --push \
  .

发布成功后，仓库里同一个 team/demo:1.0 标签对应一个索引以及两个平台 manifest。下游在 amd64 主机上拉取时会选择 amd64 变体，在 arm64 主机上则选择 arm64 变体。这里的“一个标签”不代表只上传了一个文件，而是把索引和它引用的各平台内容作为一组推送。

Go 等可交叉编译项目，优先把编译阶段固定在 BUILDPLATFORM

如果镜像里编译的是 Go、Rust 或其他支持交叉编译的程序，不一定要让 BuildKit 用仿真执行编译器。以 Go 为例，可以让编译阶段运行在 builder 自身平台，再把 TARGETOS 和 TARGETARCH 传给编译器。

# syntax=docker/dockerfile:1
# 编译阶段固定在构建机平台，避免为每个目标平台仿真运行编译器
FROM --platform=$BUILDPLATFORM golang:alpine AS build

# 这两个参数由 BuildKit 注入，分别表示目标系统和目标架构
ARG TARGETOS
ARG TARGETARCH
WORKDIR /src
COPY . .

# 用目标平台参数生成对应的二进制文件
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/server ./cmd/server

# 运行阶段仍然按目标平台选择基础镜像
FROM alpine:3.20
COPY --from=build /out/server /server
ENTRYPOINT ["/server"]

这个模式的关键不是把 BUILDPLATFORM 写进最终镜像，而是把“编译器在哪个平台运行”和“最终程序要去哪个平台运行”拆开。若项目依赖 CGO 或其他原生库，交叉编译条件会变复杂，此时要重新评估原生多节点或仿真方案。

本地加载、标签和 CI 中的三个边界

不要把 --load 和 --push 当作同一个出口。传统 Docker Engine 的本地镜像存储通常不能直接接收多平台结果；需要在本地测试时，可以按单个平台构建并 --load，正式交付时再用 --push。如果确实需要把多平台结果加载到本地，需要使用支持 containerd image store 的配置。

标签要稳定，平台要显式。推荐在发布命令中明确写出平台列表和完整 tag，不要依赖当前机器的默认平台。多平台标签可以使用版本号或提交号，避免把一次重建误当成同一个不可追踪产物。

CI 里把登录、builder、平台和推送放在同一条链路。GitHub Actions 可以使用 Docker 官方的 setup-buildx、setup-qemu 和 build-push-action；多平台工作的核心输入仍然是 platforms: linux/amd64,linux/arm64 与 push: true。

# CI 中把登录、builder 和多平台推送串起来
steps:
  - name: Set up Buildx
    uses: docker/setup-buildx-action@v4
  - name: Build and push
    uses: docker/build-push-action@v7
    with:
      context: .
      # 明确声明最终要交付的两个平台
      platforms: linux/amd64,linux/arm64
      push: true
      tags: registry.example.com/team/demo:${{ github.sha }}

几个容易混淆的问题

只写两个平台就一定能构建成功吗？ 不一定。builder 需要运行目标平台的 RUN 指令，或者 Dockerfile 必须改成可交叉编译；先用 buildx inspect --bootstrap 看能力。

为什么多平台构建后本地找不到镜像？ 因为没有指定输出时，BuildKit 不会自动把多平台结果加载到传统本地镜像存储。正式交付使用 --push，本地调试则按平台使用 --load。

manifest list 是不是又一个 Dockerfile？ 不是。它是描述多个平台 manifest 的索引对象，Docker 客户端据此选择与当前主机匹配的镜像变体。

把多平台发布做稳定，核心只有三件事：显式列出目标平台，确保 builder 有对应的执行或交叉编译能力，再用 --push 把索引和各平台 manifest 一起交付。这样开发机、CI 和生产节点可以共用同一个镜像标签，同时保留各架构独立的实际内容。