buildx

buildx 是一个 Docker CLI 插件，通过 BuildKit 提供扩展的构建功能。

主要特性：

• 与 docker build 相似的用户界面
• 使用容器驱动程序实现完整的 BuildKit 功能
• 支持多个构建器实例
• 用于跨平台镜像的多节点构建
• 支持 Compose 构建
• 高级构建结构（bake）
• 支持容器内驱动程序（Docker 和 Kubernetes）

目录

• 安装
  • Windows 和 macOS
  • Linux 包
  • 手动下载
  • Dockerfile
• 将 buildx 设置为默认构建器
• 构建
• 入门
  • 使用 buildx 构建
  • 使用构建器实例
  • 构建多平台镜像
• 参考
  • buildx bake
  • buildx build
  • buildx create
  • buildx du
  • buildx imagetools
    • buildx imagetools create
    • buildx imagetools inspect
  • buildx inspect
  • buildx ls
  • buildx prune
  • buildx rm
  • buildx stop
  • buildx use
  • buildx version
• 贡献

有关如何使用 Buildx 的更多信息，请参阅 Docker Build 文档。

安装

使用 buildx 需要 Docker 引擎 19.03 或更高版本。

警告

使用不兼容的 Docker 版本可能会导致意外行为，并可能引发问题，特别是在使用较新版本的 BuildKit 的 Buildx 构建器时。

Windows 和 macOS

Docker Buildx 已包含在 Windows 和 macOS 的 Docker Desktop 中。

Linux 包

按照 Docker 引擎安装文档 安装时，Docker 引擎包存储库包含 Docker Buildx 包。安装 docker-buildx-plugin 包以安装 Buildx 插件。

手动下载

重要提示

本节适用于 buildx 组件的无人值守安装。这些说明主要适用于测试目的。我们不建议在生产环境中使用手动下载方式安装 buildx，因为它们不会自动更新安全补丁。

在 Windows 和 macOS 上，我们建议您安装 Docker Desktop。对于 Linux，我们建议您按照特定于您的发行版的说明进行操作。

您也可以从 GitHub 发布页面 下载最新的二进制文件。

重命名相关二进制文件并将其复制到与您的操作系统匹配的目标位置：

或将其复制到以下文件夹之一以进行系统范围的安装。

在 Unix 环境中：

• /usr/local/lib/docker/cli-plugins 或 /usr/local/libexec/docker/cli-plugins
• /usr/lib/docker/cli-plugins 或 /usr/libexec/docker/cli-plugins

在 Windows 中：

• C:\ProgramData\Docker\cli-plugins
• C:\Program Files\Docker\cli-plugins

注意

在 Unix 环境中，可能还需要使用 chmod +x 使其可执行：

$ chmod +x ~/.docker/cli-plugins/docker-buildx

Dockerfile

以下是如何通过 docker/buildx-bin 镜像在 Dockerfile 中安装和使用 Buildx：

# syntax=docker/dockerfile:1
FROM docker
COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-buildx
RUN docker buildx version

将 buildx 设置为默认构建器

运行 docker buildx install 命令将 docker builder 命令设置为 docker buildx build 的别名。这样就可以让 docker build 使用当前的 buildx 构建器。

要移除此别名，请运行 docker buildx uninstall。

构建

# Buildx 0.6+
$ docker buildx bake "https://github.com/docker/buildx.git"
$ mkdir -p ~/.docker/cli-plugins
$ mv ./bin/build/buildx ~/.docker/cli-plugins/docker-buildx

# Docker 19.03+
$ DOCKER_BUILDKIT=1 docker build --platform=local -o . "https://github.com/docker/buildx.git"
$ mkdir -p ~/.docker/cli-plugins
$ mv buildx ~/.docker/cli-plugins/docker-buildx

# 本地
$ git clone https://github.com/docker/buildx.git && cd buildx
$ make install

入门

使用 buildx 构建

Buildx 是一个 Docker CLI 插件，它扩展了 docker build 命令，提供 Moby BuildKit 构建器工具包的全部功能支持。它提供与 docker build 相同的用户体验，同时还有许多新功能，如创建作用域构建器实例和同时针对多个节点构建。

安装后，可以通过 Docker 19.03 中的 docker buildx 命令访问 buildx。docker buildx build 是启动新构建的命令。对于 19.03 之前的 Docker 版本，可以直接调用 buildx 二进制文件来访问 docker buildx 子命令。

$ docker buildx build .
[+] Building 8.4s (23/32)
 => ...

Buildx 将始终使用 BuildKit 引擎进行构建，不需要设置 DOCKER_BUILDKIT=1 环境变量来启动构建。

docker buildx build 命令支持 docker build 可用的功能，包括输出配置、内联构建缓存和指定目标平台等功能。此外，Buildx 还支持常规 docker build 尚不可用的新功能，如构建清单列表、分布式缓存和将构建结果导出到 OCI 镜像 tarball。

Buildx 具有灵活性，可以在通过各种"驱动程序"公开的不同配置中运行。每个驱动程序定义了构建应如何以及在何处运行，并具有不同的功能集。

我们目前支持以下驱动程序：

• docker 驱动程序（指南，参考）
• docker-container 驱动程序（指南，参考）
• kubernetes 驱动程序（指南，参考）
• remote 驱动程序（指南）

有关驱动程序的更多信息，请参阅驱动程序指南。

使用构建器实例

默认情况下，如果支持的话，buildx 最初将使用 docker 驱动程序，提供与原生 docker build 非常相似的用户体验。请注意，您必须使用本地共享守护进程来构建应用程序。

Buildx 允许您创建新的隔离构建器实例。这可用于为您的 CI 构建获得一个范围内的环境，该环境不会改变共享守护进程的状态，或者用于隔离不同项目的构建。您可以为一组远程节点创建一个新实例，形成一个构建农场，并快速在它们之间切换。

您可以使用 docker buildx create 命令创建新实例。这将根据您当前的配置创建一个具有单个节点的新构建器实例。 要使用远程节点，您可以在创建新构建器时指定 DOCKER_HOST 或远程上下文名称。创建新实例后，您可以使用 [docker buildx inspect]、[docker buildx stop] 和 [docker buildx rm] 命令来管理其生命周期。要列出所有可用的构建器，请使用 [buildx ls]。创建新构建器后，您还可以向其添加新节点。

要在不同的构建器之间切换，请使用 [docker buildx use <name>]。运行此命令后，构建命令将自动使用该构建器。

Docker 还提供了 [docker context] 命令，可用于为远程 Docker API 端点命名。Buildx 与 docker context 集成，因此所有上下文都会自动获得默认的构建器实例。在创建新的构建器实例或向其添加节点时，您还可以将上下文名称设置为目标。

构建多平台镜像

BuildKit 设计用于构建多平台镜像，而不仅仅适用于执行构建的用户所运行的架构和操作系统。

调用构建时，您可以设置 --platform 标志来指定构建输出的目标平台（例如，linux/amd64、linux/arm64 或 darwin/amd64）。

当当前构建器实例由 docker-container 或 kubernetes 驱动程序支持时，您可以同时指定多个平台。在这种情况下，它会构建一个包含所有指定架构镜像的清单列表。当您在 [docker run] 或 [docker service] 中使用此镜像时，Docker 会根据节点的平台选择正确的镜像。

您可以使用 Buildx 和 Dockerfile 支持的三种不同策略来构建多平台镜像：

1. 使用内核中的 QEMU 模拟支持
2. 在同一构建器实例上使用多个原生节点进行构建
3. 使用 Dockerfile 中的阶段来交叉编译不同架构

如果您的节点已支持 QEMU（例如，如果您使用 Docker Desktop），那么这是最简单的入门方式。它不需要对 Dockerfile 进行任何更改，BuildKit 会自动检测可用的次要架构。当 BuildKit 需要为不同架构运行二进制文件时，它会自动通过注册在 binfmt_misc 处理程序中的二进制文件加载它。

要使主机操作系统上通过 binfmt_misc 注册的 QEMU 二进制文件在容器内透明工作，它们必须使用 fix_binary 标志注册。这需要内核 >= 4.8 和 binfmt-support >= 2.1.7。您可以通过检查 /proc/sys/fs/binfmt_misc/qemu-* 中的标志是否包含 F 来验证是否正确注册。虽然 Docker Desktop 预先配置了对其他平台的 binfmt_misc 支持，但对于其他安装，可能需要使用 [tonistiigi/binfmt] 镜像进行安装。

$ docker run --privileged --rm tonistiigi/binfmt --install all

使用多个原生节点可以更好地支持 QEMU 无法处理的复杂情况，并且通常具有更好的性能。您可以使用 --append 标志向构建器实例添加额外的节点。

假设 docker context ls 中存在 node-amd64 和 node-arm64 上下文：

$ docker buildx create --use --name mybuild node-amd64
mybuild
$ docker buildx create --append --name mybuild node-arm64
$ docker buildx build --platform linux/amd64,linux/arm64 .

最后，根据您的项目，您使用的语言可能对交叉编译有很好的支持。在这种情况下，可以有效地使用 Dockerfile 中的多阶段构建，使用构建节点的原生架构为 --platform 指定的平台构建二进制文件。一系列构建参数（如 BUILDPLATFORM 和 TARGETPLATFORM）在 Dockerfile 中自动可用，可以被构建过程中运行的进程利用。

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log
FROM alpine
COPY --from=build /log /log

您还可以使用 [tonistiigi/xx] Dockerfile 交叉编译助手来处理更高级的用例。

高级构建选项

有关更多详细信息，请参阅[使用 Bake 进行高级构建]。

贡献

想为 Buildx 做贡献？太棒了！您可以在 [CONTRIBUTING.md] 中找到有关为该项目做贡献的信息。