Docker Buildx 多架构镜像构建指南
本文档记录了使用 Docker buildx 配置多架构（amd64 / arm64 等）构建环境的完整步骤与示例。
前置准备：配置多架构构建环境
在多架构机器（如 arm64 服务器）上构建 amd64 镜像，或需要同时构建多架构镜像时，需安装 QEMU 模拟器并创建 buildx builder。
1. 安装 binfmt 模拟器
为内核注册 QEMU 二进制格式处理器，使宿主机能直接执行其他架构的二进制文件。
docker run --rm --privileged tonistiigi/binfmt --install all || true
示例输出：
root@sg:~# docker run --rm --privileged tonistiigi/binfmt --install all || true
Unable to find image 'tonistiigi/binfmt:latest' locally
latest: Pulling from tonistiigi/binfmt
0c46aa6e9c41: Pull complete
56685a25fbf3: Pull complete
44136fa355b3: Download complete
76bf583f0cc9: Download complete
c9e92217fbff: Download complete
Digest: sha256:400a4873b838d1b89194d982c45e5fb3cda4593fbfd7e08a02e76b03b21166f0
Status: Downloaded newer image for tonistiigi/binfmt:latest
installing: arm64 OK
installing: s390x OK
installing: ppc64le OK
installing: mips64 OK
installing: loong64 OK
installing: arm OK
installing: riscv64 OK
installing: mips64le OK
{
"supported": [
"linux/amd64",
"linux/amd64/v2",
"linux/amd64/v3",
"linux/amd64/v4",
"linux/arm64",
"linux/riscv64",
"linux/ppc64le",
"linux/s390x",
"linux/386",
"linux/mips64le",
"linux/mips64",
"linux/loong64",
"linux/arm/v7",
"linux/arm/v6"
],
"emulators": [
"python3.11",
"qemu-aarch64",
"qemu-arm",
"qemu-loongarch64",
"qemu-mips64",
"qemu-mips64el",
"qemu-ppc64le",
"qemu-riscv64",
"qemu-s390x"
]
}
root@sg:~#
--privileged是必须的，因为向内核注册二进制格式处理器需要特权。|| true确保即使已有安装也不会中断脚本。
2. 创建 buildx builder
使用 docker-container 驱动创建多架构构建器，相比默认的 docker 驱动，它支持并发多平台构建和缓存。
docker buildx create --name ci-builder --use --driver docker-container --driver-opt image=moby/buildkit:buildx-stable-1 || docker buildx use ci-builder
| 参数 | 说明 |
|---|---|
--name ci-builder |
构建器名称 |
--use |
创建后立即设为当前构建器 |
--driver docker-container |
使用 docker-container 驱动（独立 BuildKit 容器） |
--driver-opt image=... |
指定 BuildKit 镜像版本 |
查看构建器列表：
docker buildx ls
root@sg:~# docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
ci-builder* docker-container
\_ ci-builder0 \_ unix:///var/run/docker.sock inactive
default docker
\_ default \_ default running v0.31.0 linux/amd64 (+4), linux/arm64, linux/arm (+2), linux/ppc64le, (5 more)
root@sg:~#
*表示当前使用的构建器。
3. 启动并检查 builder
首次启动 builder 会自动拉取 BuildKit 镜像并创建容器。
docker buildx inspect --bootstrap
# docker buildx inspect --bootstrap --builder ci-builder
示例输出
root@sg:~# docker buildx inspect --bootstrap
[+] Building 11.2s (1/1) FINISHED
=> [internal] booting buildkit 11.0s
=> => pulling image moby/buildkit:buildx-stable-1 8.6s
=> => creating container buildx_buildkit_ci-builder0 2.4s
Name: ci-builder
Driver: docker-container
Last Activity: 2026-07-18 16:57:22 +0000 UTC
Nodes:
Name: ci-builder0
Endpoint: unix:///var/run/docker.sock
Driver Options: image="moby/buildkit:buildx-stable-1"
Status: running
BuildKit daemon flags: --allow-insecure-entitlement=network.host
BuildKit version: v0.31.2
Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/loong64, linux/arm/v7, linux/arm/v6
Labels:
org.mobyproject.buildkit.worker.executor: oci
org.mobyproject.buildkit.worker.hostname: cbe1da50be79
org.mobyproject.buildkit.worker.network: host
org.mobyproject.buildkit.worker.oci.process-mode: sandbox
org.mobyproject.buildkit.worker.selinux.enabled: false
org.mobyproject.buildkit.worker.snapshotter: overlayfs
GC Policy rule#0:
All: false
Filters: type==source.local type==exec.cachemount type==source.git.checkout
Keep Duration: 48h0m0s
Max Used Space: 488.3MiB
GC Policy rule#1:
All: false
Keep Duration: 1440h0m0s
Reserved Space: 1.863GiB
Max Used Space: 14.9GiB
Min Free Space: 3.725GiB
GC Policy rule#2:
All: false
Reserved Space: 1.863GiB
Max Used Space: 14.9GiB
Min Free Space: 3.725GiB
GC Policy rule#3:
All: true
Reserved Space: 1.863GiB
Max Used Space: 14.9GiB
Min Free Space: 3.725GiB
root@sg:~#
构建镜像
单平台构建
docker buildx build \
--platform linux/amd64 \
-t <image-name>:<tag> \
--load \
.
多平台构建
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t <image-name>:<tag> \
--push \
.
| 参数 | 说明 |
|---|---|
--platform |
目标平台列表，逗号分隔（如 linux/amd64,linux/arm64） |
--load |
加载到本地 Docker（仅单平台） |
--push |
直接推送到镜像仓库（多平台必须） |
--no-cache |
不使用构建缓存 |
--progress plain |
显示详细构建过程 |
-t, --tag |
镜像名称与标签 |
注意：
docker-container驱动不支持--load，多平台镜像需通过--push推送到 registry 后拉取使用。
验证测试
创建一个最小 Dockerfile 快速验证多架构构建环境是否正常工作：
cat > Dockerfile <<'EOF'
FROM debian:13.6
RUN uname -a
EOF
docker buildx build -f Dockerfile . \
--platform linux/amd64,linux/arm64 \
-t test:0.0.1 \
--no-cache --progress plain
示例输出（amd64 输出 x86_64，arm64 输出 aarch64）
root@sg:~# docker buildx build -f Dockerfile . --platform linux/amd64,linux/arm64 -t test:0.0.1 --no-cache --progress plain
#0 building with "ci-builder" instance using docker-container driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 69B 0.0s done
#1 DONE 0.0s
#2 [linux/arm64 internal] load metadata for docker.io/library/debian:13.6
#2 ...
#3 [linux/amd64 internal] load metadata for docker.io/library/debian:13.6
#3 DONE 2.1s
#4 [internal] load .dockerignore
#4 transferring context: 2B done
#4 DONE 0.0s
#2 [linux/arm64 internal] load metadata for docker.io/library/debian:13.6
#2 DONE 2.4s
#5 [linux/arm64 1/2] FROM docker.io/library/debian:13.6@sha256:fac46bff2e02f51425b6e33b0e1169f55dfb053d83511ca28aa50c09fd5ed7a4
#5 resolve docker.io/library/debian:13.6@sha256:fac46bff2e02f51425b6e33b0e1169f55dfb053d83511ca28aa50c09fd5ed7a4 done
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 0B / 49.67MB 0.2s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 3.15MB / 49.67MB 0.9s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 6.29MB / 49.67MB 2.3s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 9.44MB / 49.67MB 3.5s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 13.63MB / 49.67MB 3.8s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 31.48MB / 49.67MB 3.9s
#5 sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 49.67MB / 49.67MB 4.1s done
#5 extracting sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563
#5 ...
#6 [linux/amd64 1/2] FROM docker.io/library/debian:13.6@sha256:fac46bff2e02f51425b6e33b0e1169f55dfb053d83511ca28aa50c09fd5ed7a4
#6 resolve docker.io/library/debian:13.6@sha256:fac46bff2e02f51425b6e33b0e1169f55dfb053d83511ca28aa50c09fd5ed7a4 done
#6 sha256:b890c9407285c31d25426ef154b55c72e225f19b478a59451b01a8a44f5ea4f7 49.31MB / 49.31MB 4.1s done
#6 extracting sha256:b890c9407285c31d25426ef154b55c72e225f19b478a59451b01a8a44f5ea4f7 2.4s done
#6 DONE 6.5s
#5 [linux/arm64 1/2] FROM docker.io/library/debian:13.6@sha256:fac46bff2e02f51425b6e33b0e1169f55dfb053d83511ca28aa50c09fd5ed7a4
#5 extracting sha256:6b89e501e8efce0d3d87e3f6b0f85c417e799a3b36b8f44419609ba7fecf9563 2.5s done
#5 DONE 6.6s
#7 [linux/amd64 2/2] RUN uname -a
#7 0.201 Linux buildkitsandbox 6.1.0-33-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.133-1 (2025-04-10) x86_64 GNU/Linux
#7 DONE 0.3s
#8 [linux/arm64 2/2] RUN uname -a
#8 0.223 Linux buildkitsandbox 6.1.0-33-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.133-1 (2025-04-10) aarch64 GNU/Linux
#8 DONE 0.2s
WARNING: No output specified with docker-container driver. Build result will only remain in the build cache. To push result image into registry use --push or to load image into docker use --load
root@sg:~#
x86_64表示成功在 amd64 架构执行，aarch64表示成功在 arm64 架构执行（通过 QEMU 模拟）。
CI/CD 集成
在 CI/CD 流水线中（如 runner 是 arm64 但需要构建 amd64 镜像），先安装 binfmt 再创建 builder：
# GitLab CI 示例
before_script:
- docker run --rm --privileged tonistiigi/binfmt --install all || true
- docker buildx create --name ci-builder --use --driver docker-container --driver-opt image=moby/buildkit:buildx-stable-1 || docker buildx use ci-builder
- docker buildx inspect --bootstrap
# - docker buildx inspect --bootstrap --builder ci-builder