Docker Buildx 多架构构建

FreeGuideOnline 最新 2026-07-12

bash docker --version


### 检查 Buildx 是否可用
```bash
docker buildx version

如果提示命令未找到，请参考下方手动安装 Buildx部分。

启用实验性功能（仅旧版 Docker）

对于较旧的 Docker 引擎，需要开启实验性功能。编辑 /etc/docker/daemon.json 并添加：

{
  "experimental": true
}

之后重启 Docker：

sudo systemctl restart docker

Docker Desktop 用户通常在设置中找到 Docker Engine 配置项进行修改并重启。

创建并使用 Buildx 构建器

查看现有构建器

docker buildx ls

默认会有一个名为 default 的构建器，但它的驱动通常是 docker，不支持多架构导出。我们需要创建一个新的构建器。

创建新的构建器实例

使用 docker-container 驱动，该驱动会启动一个容器来运行 BuildKit，从而完整支持多架构构建和缓存。

docker buildx create --name mybuilder --use

--name 指定构建器名称。
--use 立即将该构建器设为当前使用。

启动并检查构建器

docker buildx inspect --bootstrap

--bootstrap 会启动构建器容器并显示支持的平台列表。输出示例：

Name:   mybuilder
Driver: docker-container
...
Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 ...

编写多架构 Dockerfile

通常情况下，一个编写良好的 Dockerfile 本身不需要特殊处理即可直接用于多架构构建。但需要注意基础镜像的选择，应使用支持多架构的官方镜像或自己构建的多架构基础镜像。

示例 Dockerfile（使用 Nginx）：

FROM nginx:alpine
COPY index.html /usr/share/nginx/html/
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

nginx:alpine 官方镜像已经提供了 amd64、arm64、arm/v7 等多种架构，因此该 Dockerfile 无需修改。

如果基础镜像只有特定架构，则需借助 --platform 标志在 FROM 指令中指定：

FROM --platform=$BUILDPLATFORM golang:alpine AS builder
# ...

但更推荐使用无架构硬编码的写法，通过 Buildx 构建命令的 --platform 参数统一控制。

使用 Buildx 构建多架构镜像

基本构建命令

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t username/myapp:latest \
  --push .

参数说明：

--platform：指定目标架构，多个架构以逗号分隔。
-t：镜像标签。
--push：构建完成后直接推送到镜像仓库。如果省略 --push，由于多架构镜像的 manifest list 无法保存在本地 Docker 镜像存储中，构建将不会导出任何本地镜像。
末尾的 . 是构建上下文路径。

使用 `--load` 仅加载单一架构到本地

如果只想为当前机器架构构建并加载到本地测试，可使用 --load，此时 --platform 只能指定一个架构。

docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64-local \
  --load .

同时推送和缓存

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t username/myapp:latest \
  --cache-from=type=registry,ref=username/myapp:cache \
  --cache-to=type=registry,ref=username/myapp:cache,mode=max \
  --push .

这可以大幅加速后续构建，特别是对于多架构场景。

高级用法

使用 QEMU 实现跨架构仿真

当本地机器架构与目标架构不同时（如在 Intel 电脑上构建 ARM 镜像），Buildx 会借助 QEMU 进行二进制翻译。现代 Docker Desktop 和 Linux 通常已经自动处理。若未启用，可运行以下命令注册 QEMU 二进制格式：

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

并行构建

Buildx 默认会并行构建多个架构，利用多个 CPU 核心加速。

自定义构建输出

Buildx 支持多种输出类型，例如直接导出到本地 tar 文件：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --output type=tar,dest=multi.tar .

利用 Bake 同时构建多个项目

对于包含多个服务的项目，可以使用 HCL 或 JSON 格式的 Bake 文件集中定义构建配置，然后一个命令构建所有镜像：

docker buildx bake

实用场景：为树莓派和云主机构建同一镜像

假设你要部署一个 Web 应用到 x86 云服务器和树莓派集群：

确保 Dockerfile 使用多架构基础镜像（如 python:3.11-slim）。
创建并使用新的构建器。
执行构建并推送：

docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t myrepo/webapp:1.0 \
  --push .

在不同设备上直接 docker pull myrepo/webapp:1.0，会自动拉取正确架构的镜像。

常见问题与排错

无法推送镜像

确保已使用 docker login 登录到目标仓库（Docker Hub 或私有仓库）。

构建时提示 “multiple platforms feature is currently not supported”

通常是因为使用了 default 构建器。请执行 docker buildx use mybuilder 切换到自定义构建器。

构建速度慢

确保启用缓存 --cache-from 和 --cache-to。
减少 --platform 数量。
在多核机器上并行执行。

QEMU 相关问题

在非 x86 宿主机上构建 x86 镜像时，如果遇到报错，重新执行 docker run --rm --privileged multiarch/qemu-user-static --reset -p yes 通常能解决。

手动安装 Buildx

如果 Docker 环境中没有 Buildx，可以手动安装：

从 GitHub Release 下载对应平台的二进制文件。
将其放到 Docker 的插件目录（~/.docker/cli-plugins/）并赋予可执行权限：

mkdir -p ~/.docker/cli-plugins
mv buildx ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx

检查安装：

docker buildx version