鱼梦江湖 @Yumengjh

简体中文

English

简体中文

English

外观

Docker Buildx

复制页面

约 3340 字大约 11 分钟

2025-10-11

简介

什么是 Docker Buildx？

Docker Buildx 是 Docker 官方提供的一个 CLI 插件，它扩展了 docker build 命令的功能。其核心是建立在 Moby BuildKit 之上的下一代镜像构建工具。

你可以把它理解为 docker build 命令的增强版。它保留了用户熟悉的 docker build 使用体验，但同时增加了许多强大的新特性，其中最核心的就是跨平台构建。

为什么需要 Buildx？

  1. 跨平台构建困难：在 x86_64 的机器上，很难直接构建出适用于 ARM（例如树莓派）、PowerPC 等架构的镜像。传统方法需要复杂的交叉编译环境或在对应架构的机器上进行构建。
  2. 构建性能瓶颈：传统的 Docker 构建器在某些方面效率不高。
  3. 功能单一：传统的 docker build 缺乏对复杂构建场景（如多镜像并发构建、高级缓存管理）的原生支持。

Buildx 的核心特性

跨平台构建

这是 Buildx 最引人注目的功能。它允许你在一台机器上（例如，你的 Intel Mac 或 AMD Linux 电脑）为多种不同的 CPU 架构构建 Docker 镜像。

支持的平台包括：

  • linux/amd64 (常规的 Intel/AMD 服务器和桌面)
  • linux/arm64 (苹果 M1/M2 Mac，AWS Graviton 处理器，现代树莓派)
  • linux/arm/v7 (旧版树莓派等)
  • linux/ppc64le
  • linux/s390x
  • windows/amd64

实现方式： Buildx 通过 QEMU 仿真和 BuildKit 的能力，在后台自动模拟目标平台的环境，使得构建过程就像在目标平台上进行一样。

高效的构建缓存

Buildx 提供了比传统构建更强大的缓存机制，支持将缓存信息存储在本地、注册表内或特定的缓存卷中。这在与 CI/CD 流水线集成时特别有用，可以大幅加速后续构建。

并发构建

可以一次性为多个平台构建镜像，而不是逐个平台地执行 docker build 命令。这极大地提升了效率。

可扩展的构建器后端

Buildx 支持不同的“构建器实例”。你可以创建使用不同配置的构建器，例如：

  • docker-container 驱动：这是功能最强大的驱动，支持跨平台构建等所有高级功能。
  • docker 驱动：使用与旧版 docker build 相同的守护进程，功能有限。
  • kubernetes 驱动：在 Kubernetes Pod 中运行构建任务。

创建清单列表

当你为多个平台构建镜像后，Buildx 可以自动创建一个 Docker 清单列表。这个清单指向所有不同架构的镜像。当用户使用 docker pull 或 docker run 时，Docker 会自动根据其系统架构选择正确的镜像。

如何使用 Docker Buildx

前提条件

  • Docker Engine 版本 19.03 或更高。
  • 对于 Linux，需要额外安装 QEMU 静态二进制文件以支持跨平台构建（通常通过 binfmt-support 包）。

基本使用步骤

  1. 启用实验性功能（如果尚未启用）：编辑 ~/.docker/config.json 文件，确保包含：
{
  "experimental": "enabled"
}

然后重启 Docker 守护进程。

  1. 创建并使用一个 Buildx 构建器：默认的构建器可能功能有限，建议创建一个新的。
# 创建一个新的构建器实例，并使用 'docker-container' 驱动
docker buildx create --name mybuilder --driver docker-container --bootstrap

# 使用这个构建器
docker buildx use mybuilder
  1. 检查构建器状态：
docker buildx inspect mybuilder
  1. 开始构建：

单平台构建（与 docker build 类似）：

docker buildx build -t your-username/your-app:latest .

多平台构建（核心功能）：

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

--platform：指定目标平台列表。

--push：构建完成后，自动将镜像和清单列表推送到 Docker Hub 或其他容器注册中心。如果不加此参数，构建结果只会存在于本地缓存中，无法被 docker images 看到或使用。

  1. 查看支持的平台：
docker buildx ls

实战示例

假设你有一个 Go 语言应用，想要为 Intel 和 Apple Silicon Mac 以及树莓派构建镜像。

准备 Dockerfile:
# 使用多阶段构建
FROM --platform=$BUILDPLATFORM golang:1.19 AS builder
ARG TARGETARCH
WORKDIR /app
COPY . .
RUN GOOS=linux GOARCH=$TARGETARCH go build -o myapp .

FROM alpine:latest
WORKDIR /root/
COPY --from=builder /app/myapp .
CMD ["./myapp"]
执行 Buildx 多平台构建并推送:
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  -t your-dockerhub-username/multi-arch-example:latest \
  --push \
  .
验证：

构建并推送成功后，你可以在 Docker Hub 上看到该标签下关联了多个架构的镜像。

任何人使用 docker pull your-dockerhub-username/multi-arch-example:latest 时，Docker 都会自动为他们分配合适的架构版本。

总结

特性传统 docker buildDocker Buildx
核心功能单平台镜像构建跨平台构建，支持一次构建多架构镜像
构建后端旧版构建器BuildKit（性能更好，功能更强）
输出单一镜像支持创建多架构清单列表
缓存基础缓存高级、可配置的缓存后端（如注册表缓存）
并发性无支持并发多平台构建

总而言之，Docker Buildx 是现代 Docker 镜像构建的推荐工具。 尤其是当你需要支持多种硬件架构（如云服务器、个人电脑、物联网设备）时，它几乎是不可或缺的，能极大地简化和加速你的 CI/CD 和工作流程。

使用 BuildKit 构建镜像

BuildKit 是下一代的镜像构建组件，在 https://github.com/moby/buildkit 开源。

注意：如果您的镜像构建使用的是云服务商提供的镜像构建服务（腾讯云容器服务、阿里云容器服务等），由于上述服务提供商的 Docker 版本低于 18.09，BuildKit 无法使用，将造成镜像构建失败。建议使用 BuildKit 构建镜像时使用一个新的 Dockerfile 文件（例如 Dockerfile.buildkit）

目前，Docker Hub 自动构建已经支持 buildkit，具体请参考 https://github.com/docker-practice/docker-hub-buildx

Dockerfile 新增指令详解

启用 BuildKit 之后，我们可以使用下面几个新的 Dockerfile 指令来加快镜像构建。

RUN --mount=type=cache

目前，几乎所有的程序都会使用依赖管理工具，例如 Go 中的 go mod、Node.js 中的 npm 等等，当我们构建一个镜像时，往往会重复的从互联网中获取依赖包，难以缓存，大大降低了镜像的构建效率。

例如一个前端工程需要用到 npm：

FROM node:alpine as builder

WORKDIR /app

COPY package.json /app/

RUN npm i --registry=https://registry.npm.taobao.org \
        && rm -rf ~/.npm

COPY src /app/src

RUN npm run build

FROM nginx:alpine

COPY --from=builder /app/dist /app/dist

使用多阶段构建，构建的镜像中只包含了目标文件夹 dist，但仍然存在一些问题，当 package.json 文件变动时，RUN npm i && rm -rf ~/.npm 这一层会重新执行，变更多次后，生成了大量的中间层镜像。

为解决这个问题，进一步的我们可以设想一个类似 数据卷 的功能，在镜像构建时把 node_modules 文件夹挂载上去，在构建完成后，这个 node_modules 文件夹会自动卸载，实际的镜像中并不包含 node_modules 这个文件夹，这样我们就省去了每次获取依赖的时间，大大增加了镜像构建效率，同时也避免了生成了大量的中间层镜像。

BuildKit 提供了 RUN --mount=type=cache 指令，可以实现上边的设想。

# syntax = docker/dockerfile:experimental
FROM node:alpine as builder

WORKDIR /app

COPY package.json /app/

RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
    --mount=type=cache,target=/root/.npm,id=npm_cache \
        npm i --registry=https://registry.npm.taobao.org

COPY src /app/src

RUN --mount=type=cache,target=/app/node_modules,id=my_app_npm_module,sharing=locked \
# --mount=type=cache,target=/app/dist,id=my_app_dist,sharing=locked \
        npm run build

FROM nginx:alpine

# COPY --from=builder /app/dist /app/dist

# 为了更直观的说明 from 和 source 指令，这里使用 RUN 指令
RUN --mount=type=cache,target=/tmp/dist,from=builder,source=/app/dist \
    # --mount=type=cache,target/tmp/dist,from=my_app_dist,sharing=locked \
    mkdir -p /app/dist && cp -r /tmp/dist/* /app/dist

由于 BuildKit 为实验特性，每个 Dockerfile 文件开头都必须加上如下指令

# syntax = docker/dockerfile:experimental

第一个 RUN 指令执行后，id 为 my_app_npm_module 的缓存文件夹挂载到了 /app/node_modules 文件夹中。多次执行也不会产生多个中间层镜像。

第二个 RUN 指令执行时需要用到 node_modules 文件夹，node_modules 已经挂载，命令也可以正确执行。

第三个 RUN 指令将上一阶段产生的文件复制到指定位置，from 指明缓存的来源，这里 builder 表示缓存来源于构建的第一阶段，source 指明缓存来源的文件夹。

上面的 Dockerfile 中 --mount=type=cache,... 中指令作用如下：

OptionDescription
idid 设置一个标志，以便区分缓存。
target (必填项)缓存的挂载目标文件夹。
ro,readonly只读，缓存文件夹不能被写入。
sharing有 shared private locked 值可供选择。sharing 设置当一个缓存被多次使用时的表现，由于 BuildKit 支持并行构建，当多个步骤使用同一缓存时（同一 id）会发生冲突。shared 表示多个步骤可以同时读写，private 表示当多个步骤使用同一缓存时，每个步骤使用不同的缓存，locked 表示当一个步骤完成释放缓存后，后一个步骤才能继续使用该缓存。
from缓存来源（构建阶段），不填写时为空文件夹。
source来源的文件夹路径。

RUN --mount=type=bind

该指令可以将一个镜像（或上一构建阶段）的文件挂载到指定位置。

# syntax = docker/dockerfile:experimental
RUN --mount=type=bind,from=php:alpine,source=/usr/local/bin/docker-php-entrypoint,target=/docker-php-entrypoint \
        cat /docker-php-entrypoint

RUN --mount=type=tmpfs

该指令可以将一个 tmpfs 文件系统挂载到指定位置。

# syntax = docker/dockerfile:experimental
RUN --mount=type=tmpfs,target=/temp \
        mount | grep /temp

RUN --mount=type=secret

该指令可以将一个文件(例如密钥)挂载到指定位置。

# syntax = docker/dockerfile:experimental
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
        cat /root/.aws/credentials
docker build -t test --secret id=aws,src=$HOME/.aws/credentials .

RUN --mount=type=ssh

该指令可以挂载 ssh 密钥。

# syntax = docker/dockerfile:experimental
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh git@gitlab.com | tee /hello
eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
docker build -t test --ssh default=$SSH_AUTH_SOCK .

docker-compose build 使用 Buildkit

设置 COMPOSE_DOCKER_CLI_BUILD=1 环境变量即可使用。

使用 Buildx 构建镜像

你可以直接使用 docker buildx build 命令构建镜像。

docker buildx build .

[+] Building 8.4s (23/32)
 => ...

Buildx 使用 BuildKit 引擎 进行构建，并且支持许多新的功能

使用 buildx 构建多种系统架构支持的 Docker 镜像

在之前的版本中构建多种系统架构支持的 Docker 镜像，要想使用统一的名字必须使用 docker manifest 命令。

在 Docker 19.03+ 版本中可以使用 docker buildx build 命令使用 BuildKit 构建镜像。该命令支持 --platform 参数可以同时构建支持多种系统架构的 Docker 镜像，大大简化了构建步骤。

新建 builder 实例

Docker for Linux 不支持构建 arm 架构镜像，我们可以运行一个新的容器让其支持该特性，Docker 桌面版无需进行此项设置。

docker run --rm --privileged tonistiigi/binfmt:latest --install all

由于 Docker 默认的 builder 实例不支持同时指定多个 --platform，我们必须首先创建一个新的 builder 实例。

同时由于国内拉取镜像较缓慢，我们可以使用配置了 镜像加速地址 的 dockerpracticesig/buildkit:master镜像替换官方镜像。

如果你有私有的镜像加速器，可以基于 https://github.com/docker-practice/buildx 构建自己的 buildkit 镜像并使用它。

# 适用于国内环境
docker buildx create --use --name=mybuilder-cn --driver docker-container --driver-opt image=dockerpracticesig/buildkit:master

# 适用于腾讯云环境(腾讯云主机、coding.net 持续集成)
docker buildx create --use --name=mybuilder-cn --driver docker-container --driver-opt image=dockerpracticesig/buildkit:master-tencent

# $ docker buildx create --name mybuilder --driver docker-container

docker buildx use mybuilder

构建镜像

新建 Dockerfile 文件。

FROM --platform=$TARGETPLATFORM alpine

RUN uname -a > /os.txt

CMD cat /os.txt

使用 docker buildx build 命令构建镜像，注意将 myusername 替换为自己的 Docker Hub 用户名。

--push 参数表示将构建好的镜像推送到 Docker 仓库。

docker buildx build --platform linux/arm,linux/arm64,linux/amd64 -t myusername/hello . --push

# 查看镜像信息
docker buildx imagetools inspect myusername/hello

在不同架构运行该镜像，可以得到该架构的信息。

# arm
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 armv7l Linux

# arm64
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 aarch64 Linux

# amd64
docker run -it --rm myusername/hello
Linux buildkitsandbox 4.9.125-linuxkit #1 SMP Fri Sep 7 08:20:28 UTC 2018 x86_64 Linux

架构相关变量

Dockerfile 支持如下架构相关的变量

TARGETPLATFORM

构建镜像的目标平台，例如 linux/amd64, linux/arm/v7, windows/amd64。

TARGETOS

TARGETPLATFORM 的 OS 类型，例如 linux, windows

TARGETARCH

TARGETPLATFORM 的架构类型，例如 amd64, arm

TARGETVARIANT

TARGETPLATFORM 的变种，该变量可能为空，例如 v7

BUILDPLATFORM

构建镜像主机平台，例如 linux/amd64

BUILDOS

BUILDPLATFORM 的 OS 类型，例如 `linux

BUILDARCH

BUILDPLATFORM 的架构类型，例如 amd64

BUILDVARIANT

BUILDPLATFORM 的变种，该变量可能为空，例如 v7

使用举例

例如我们要构建支持 linux/arm/v7 和 linux/amd64 两种架构的镜像。假设已经生成了两个平台对应的二进制文件：

  • bin/dist-linux-arm
  • bin/dist-linux-amd64

那么 Dockerfile 可以这样书写：

FROM scratch

# 使用变量必须申明
ARG TARGETOS

ARG TARGETARCH

COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist

ENTRYPOINT ["dist"]

版权归属：yumengjh

许可证：署名 4.0 国际 (CC-BY-4.0)

建议使用现代浏览器访问本网站以获得更好的体验
Copyright © 2024-2025 鱼梦江湖 · hi@yumgjs.com