容器技术发展到现在，一个镜像跑遍所有硬件平台已经成为刚需。无论是Apple Silicon的Mac笔记本、树莓派边缘设备，还是国产化arm服务器，不同CPU架构对镜像的要求是不一样的。如果只在x86机器上构建linux/amd64镜像，直接拿到arm64机器上运行就会报exec format error错误。docker buildx正是Docker官方为了解决这类问题推出的构建工具，它内置在Docker CLI中，底层基于BuildKit引擎，配合QEMU二进制模拟技术，可以让你在一台机器上同时构建多种架构的镜像。本文从环境准备到完整构建流程，一步步讲解具体操作方法。
一、docker buildx是什么，为什么它比传统build更适合多平台构建
传统的docker build命令使用的是Docker守护进程内置的构建器，构建产物与守护进程所在的架构绑定。也就是说，你的Docker运行在amd64的Linux上，构建出来的镜像就只能是amd64架构，除非借助额外的模拟工具。而docker buildx本质上是一个CLI插件，它驱动的是BuildKit引擎，BuildKit在设计之初就考虑了多平台构建的需求。
buildx有几个核心优势值得关注。第一，它支持通过--platform参数指定多个目标平台，一次构建可以同时产出amd64和arm64等多个架构的镜像。第二，它支持多种driver，包括docker-container、kubernetes、remote等，其中docker-container driver会在本地启动一个BuildKit容器，这个容器内部可以运行QEMU，从而实现跨架构模拟。第三，buildx可以直接将多架构镜像以manifest list的形式推送到仓库，用户拉取时Docker会自动选择匹配当前架构的镜像，体验上和单架构镜像完全一致。
需要澄清一个概念：所谓多平台镜像，并不是一个镜像里塞了多个架构的二进制文件，而是同一个tag下挂了一组按架构区分的镜像列表（manifest list）。Docker在docker pull时会根据本机的架构自动挑选合适的那个。理解了这一点，后面遇到manifest相关的操作就不会疑惑了。
二、环境准备：安装buildx与QEMU模拟器
如果你使用的是Docker Desktop（Windows或Mac），buildx已经内置，QEMU支持也是默认开启的，可以直接跳到下一节。在Linux服务器上，需要手动确认几件事。首先检查Docker版本，buildx要求Docker 19.03以上，执行docker version查看。然后执行docker buildx version，如果命令不存在，说明插件没有安装，需要手动下载二进制文件放到~/.docker/cli-plugins/目录下并赋予执行权限：
mkdir -p ~/.docker/cli-plugins curl -Lo ~/.docker/cli-plugins/docker-buildx https://github.com/docker/buildx/releases/download/v0.12.1/buildx-v0.12.1.linux-amd64 chmod +x ~/.docker/cli-plugins/docker-buildx docker buildx version
第二件事是安装QEMU。QEMU负责在x86机器上模拟arm指令集，没有它，构建过程中执行ARM架构的二进制就会失败。Docker官方提供了tonistiigi/binfmt镜像来快速注册QEMU：
docker run --privileged --rm tonistiigi/binfmt --install all
注意这个命令必须带--privileged参数，因为注册binfmt_misc处理器需要修改内核的注册表项，普通权限做不到。安装完成后可以用ls /proc/sys/fs/binfmt_misc/查看已经注册的处理器，里面应该能看到qemu-aarch64之类的条目。如果只是构建arm64镜像，也可以只安装特定架构：--install arm64。
这里有一个常见的坑需要提醒：如果Linux内核版本过低（比如CentOS 7默认的3.10内核），QEMU的某些架构模拟可能不完整，构建时会随机出现段错误。遇到这种情况，建议升级内核或者直接换用较新的发行版，不要在老系统上死磕。
三、创建builder实例并完成第一次多平台构建
默认的builder使用的是docker driver，它不支持多平台同时构建。所以第一步要创建一个使用docker-container driver的builder实例：
docker buildx create --name mybuilder --driver docker-container --bootstrap docker buildx use mybuilder docker buildx inspect --bootstrap
--bootstrap参数会在创建后立即启动BuildKit容器，inspect命令输出的PLATFORMS一栏显示了该builder支持的平台列表，正常应该包含linux/amd64、linux/arm64、linux/ppc64le等。如果没有，回头检查QEMU是否安装成功。
接下来准备一个简单的Dockerfile，用nginx做演示：
FROM nginx:alpine COPY index.html /usr/share/nginx/html/index.html
然后执行构建命令，一次构建两个平台并直接推送到仓库：
docker buildx build \ --platform linux/amd64,linux/arm64 \ -t yourname/multi-nginx:latest \ --push .
有几个细节要说明。多平台构建必须配合--push或者--output类型为镜像仓库的输出，因为本地Docker的镜像存储格式不支持同时保存多个架构的同名镜像。如果你只想在本地测试单架构，可以去掉一个平台，加--load参数把镜像导入本地。首次构建arm64会比较慢，QEMU模拟执行ARM指令的效率大约只有原生的十分之一，这是正常现象，后续可以利用BuildKit的缓存加速。
构建完成后，用docker buildx imagetools inspect yourname/multi-nginx:latest查看镜像详情，输出中会列出manifest list包含的各个架构条目，确认amd64和arm64都在其中就说明构建成功了。在arm机器上执行docker pull和docker run，Docker会自动拉取匹配的架构。
四、优化技巧与常见问题处理
QEMU模拟的构建速度问题有几个应对思路。最直接的是减少模拟执行的工作量：把编译类任务放在构建阶段的前端，并充分利用多阶段构建，让耗时的依赖下载和编译步骤尽可能命中缓存。如果项目对构建速度要求高，更彻底的方案是原生构建，即准备一台真实的arm64机器（云厂商基本都提供arm实例），在其中也运行一个builder，然后用docker buildx create --append把它追加为远程节点，构建时各平台在各自原生环境执行，速度和稳定性都远好于模拟方案。
另一个值得实践的技巧是在Dockerfile中使用架构相关的变量。BuildKit预置了TARGETARCH、TARGETPLATFORM等自动构建参数，可以让一份Dockerfile适配多个架构：
FROM --platform=$BUILDPLATFORM golang:1.22 AS builder ARG TARGETARCH WORKDIR /src COPY . . RUN CGO_ENABLED=0 GOOS=linux GOARCH=$TARGETARCH go build -o app . FROM alpine:3.19 COPY --from=builder /src/app /app ENTRYPOINT ["/app"]
这段Dockerfile的巧妙之处在于：构建器本身运行在$BUILDPLATFORM（构建机的原生架构）上，Go的交叉编译能力负责生成目标架构的二进制，整个过程完全不依赖QEMU，速度与原生构建一致。这也是目前构建Go、Rust这类支持交叉编译语言的多平台镜像的最佳实践。
最后说说常见报错。如果遇到multiple platforms feature is currently not supported for docker driver，说明你还在用默认builder，执行docker buildx use mybuilder切换即可。如果构建中报exec format error，基本是QEMU没有安装或注册失败，重新执行binfmt安装命令。如果推送时报权限错误，检查docker login是否执行过，并确认builder容器能访问到认证信息（docker-container driver会自动读取本地的认证配置，一般不需要额外处理）。
多平台镜像构建一旦跑通一次，就可以很自然地接入CI流水线。无论是GitHub Actions内置的docker/build-push-action，还是GitLab CI里手写buildx命令，核心步骤都和本文一致：装QEMU、建builder、指定platform、推送仓库。掌握这套流程后，你的镜像就可以真正做到一次构建，处处运行。
docker buildx多平台镜像容器镜像构建修改时间：2026-09-07 20:48:49