Docker Buildx
约 3340 字大约 11 分钟
2025-10-11
简介
什么是 Docker Buildx?
Docker Buildx 是 Docker 官方提供的一个 CLI 插件,它扩展了 docker build 命令的功能。其核心是建立在 Moby BuildKit 之上的下一代镜像构建工具。
你可以把它理解为 docker build 命令的增强版。它保留了用户熟悉的 docker build 使用体验,但同时增加了许多强大的新特性,其中最核心的就是跨平台构建。
为什么需要 Buildx?
- 跨平台构建困难:在 x86_64 的机器上,很难直接构建出适用于 ARM(例如树莓派)、PowerPC 等架构的镜像。传统方法需要复杂的交叉编译环境或在对应架构的机器上进行构建。
- 构建性能瓶颈:传统的 Docker 构建器在某些方面效率不高。
- 功能单一:传统的
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/ppc64lelinux/s390xwindows/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包)。
基本使用步骤
- 启用实验性功能(如果尚未启用):编辑
~/.docker/config.json文件,确保包含:
{
"experimental": "enabled"
}然后重启 Docker 守护进程。
- 创建并使用一个 Buildx 构建器:默认的构建器可能功能有限,建议创建一个新的。
# 创建一个新的构建器实例,并使用 'docker-container' 驱动
docker buildx create --name mybuilder --driver docker-container --bootstrap
# 使用这个构建器
docker buildx use mybuilder- 检查构建器状态:
docker buildx inspect mybuilder- 开始构建:
单平台构建(与 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 看到或使用。
- 查看支持的平台:
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 build | Docker 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,... 中指令作用如下:
| Option | Description |
|---|---|
id | id 设置一个标志,以便区分缓存。 |
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-entrypointRUN --mount=type=tmpfs
该指令可以将一个 tmpfs 文件系统挂载到指定位置。
# syntax = docker/dockerfile:experimental
RUN --mount=type=tmpfs,target=/temp \
mount | grep /tempRUN --mount=type=secret
该指令可以将一个文件(例如密钥)挂载到指定位置。
# syntax = docker/dockerfile:experimental
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
cat /root/.aws/credentialsdocker 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 /helloeval $(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-armbin/dist-linux-amd64
那么 Dockerfile 可以这样书写:
FROM scratch
# 使用变量必须申明
ARG TARGETOS
ARG TARGETARCH
COPY bin/dist-${TARGETOS}-${TARGETARCH} /dist
ENTRYPOINT ["dist"]