切换语言

docker buildx build

描述开始构建
用法docker buildx build [OPTIONS] PATH | URL | -
别名
docker build docker builder build docker image build docker buildx b

描述

docker buildx build 命令使用 BuildKit 启动构建。

选项

选项默认描述
--add-host添加自定义主机到IP的映射（格式：host:ip）
--allow允许额外的特权授权（例如，network.host, security.insecure)
--annotation为镜像添加注解
--attest证明参数 (格式: type=sbom,generator=image)
--build-arg设置构建时变量
--build-context附加构建上下文 (例如, name=path)
--cache-from外部缓存源（例如，user/app:cache, type=local,src=path/to/dir)
--cache-to缓存导出目的地（例如，user/app:cache, type=local,dest=path/to/dir)
--callbuild设置构建的评估方法（check、outline、targets）
--cgroup-parent在构建期间为 RUN 指令设置父 cgroup
--check--call=check 的简写
--detach实验性 (CLI) 分离 buildx 服务器 (仅支持 linux)
-f, --fileDockerfile 的名称（默认：PATH/Dockerfile）
--iidfile将镜像ID写入文件
--label设置镜像的元数据
--load--output=type=docker 的简写
--metadata-file将构建结果元数据写入文件
--network在构建期间为 RUN 指令设置网络模式
--no-cache构建镜像时不使用缓存
--no-cache-filter不要缓存指定的阶段
-o, --output输出目标 (格式: type=local,dest=path)
--platform设置构建的目标平台
--progressauto设置进度输出类型 (auto, plain, tty, rawjson). 使用 plain 显示容器输出
--provenance--attest=type=provenance 的简写
--pull始终尝试拉取所有引用的镜像
--push--output=type=registry 的简写
-q, --quiet抑制构建输出并在成功时打印镜像 ID
--rootexperimental (CLI) 指定要连接的服务器根目录
--sbom--attest=type=sbom 的简写
--secret要在构建中暴露的 Secret (格式:id=mysecret[,src=/local/secret])
--server-config实验性 (CLI)指定 buildx 服务器配置文件（仅在启动新服务器时使用）
--shm-size构建容器的共享内存大小
--ssh要向构建公开的 SSH 代理套接字或密钥（格式：default|<id>[=<socket>|<key>[,<key>]])
-t, --tag名称以及可选的标签（格式：name:tag）
--target设置要构建的目标构建阶段
--ulimitUlimit选项

示例

向容器 hosts 文件添加条目 (--add-host)

您可以使用一个或多个 --add-host 标志将其他主机添加到构建容器的 /etc/hosts 文件中。此示例为名为 my-hostname 和 my_hostname_v6 的主机添加静态地址：

$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .

如果您需要构建过程连接到运行在主机上的服务，您可以为 --add-host 使用特殊的 host-gateway 值。在下面的示例中，构建容器将 host.docker.internal 解析为主机的网关 IP。

$ docker buildx build --add-host host.docker.internal=host-gateway .

您可以将 IPv6 地址放在方括号中。 = 和 : 都是有效的分隔符。 以下示例中的两种格式均有效：

$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .

创建注解 (--annotation)

--annotation="key=value"
--annotation="[type:]key=value"

将 OCI 注解添加到镜像索引、清单或描述符中。 以下示例将 foo=bar 注解添加到镜像清单中：

$ docker buildx build -t TAG --annotation "foo=bar" --push .

您可以选择添加类型前缀来指定注释的级别。默认情况下，注释的是镜像清单。以下示例将 foo=bar 注释添加到镜像索引而不是清单中：

$ docker buildx build -t TAG --annotation "index:foo=bar" --push .

您可以指定多种类型，以逗号 (,) 分隔，以便将注释添加到多个镜像组件中。以下示例将 foo=bar 注解添加到镜像索引、描述符、清单：

$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .

您也可以在类型前缀的方括号（[os/arch]）中指定平台限定符，以将注解应用于具有匹配平台的清单子集。以下示例仅将 foo=bar 注解添加到具有 linux/amd64 平台的清单中：

$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .

平台限定符中不支持通配符；你不能指定像 manifest[linux/*] 这样的类型前缀来仅为具有 linux 作为 OS 平台的清单添加注解。

有关注解的更多信息，请参阅 注解。

创建证明 (--attest)

--attest=type=sbom,...
--attest=type=provenance,...

创建 镜像证明。 BuildKit 目前支持：

  • sbom - 软件物料清单。

    使用 --attest=type=sbom 在构建时为镜像生成 SBOM。 或者，您可以使用 --sbom 简写。

    欲了解更多信息，请参阅 此处。

  • provenance - SLSA 来源证明

    使用 --attest=type=provenance 在构建时生成镜像的来源。或者，您可以使用 --provenance 简写。

    默认情况下，将为构建结果创建最小来源证明，该证明仅附加到推送到注册表的镜像。

    欲了解更多信息，请参阅 此处。

允许额外的特权授权 (--allow)

--allow=ENTITLEMENT

允许额外的特权授权。授权列表：

  • network.host - 允许使用主机网络执行。
  • security.insecure - 允许在没有沙箱的情况下执行。参见 相关的 Dockerfile 扩展。

要启用权限，BuildKit 守护进程也需要通过 --allow-insecure-entitlement 允许它们（参见 create --buildkitd-flags）。

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

设置构建时变量 (--build-arg)

您可以在 Dockerfile 中使用 ENV 指令来定义变量值。这些值会保留在构建的镜像中。通常持久性并不是您想要的。用户希望根据构建镜像的主机不同，以不同的方式指定变量。

一个很好的例子是用于拉取中间文件的 http_proxy 或源代码版本。ARG 指令允许 Dockerfile 作者定义用户可以在构建时使用 --build-arg 标志设置的值：

$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .

此标志允许您传递构建时变量，这些变量在 Dockerfile 的 RUN 指令中像常规环境变量一样被访问。这些值不会像 ENV 值那样保留在中间镜像或最终镜像中。您必须为每个构建参数添加 --build-arg。

使用此标志不会改变构建过程回显 Dockerfile 中 ARG 行时看到的输出。

有关使用 ARG 和 ENV 指令的详细信息，请参阅 Dockerfile 参考。

您也可以使用不带值的 --build-arg 标志，在这种情况下，守护进程会将本地环境中的值传播到它正在构建的 Docker 容器中：

$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker buildx build --build-arg HTTP_PROXY .

此示例与 docker run -e 的工作方式类似。有关更多信息，请参阅 docker run 文档。

还有一些有用的内置构建参数，例如：

  • BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>: 触发 git 上下文以保留 .git 目录
  • BUILDKIT_INLINE_CACHE=<bool>: 是否将内联缓存元数据写入镜像配置
  • BUILDKIT_MULTI_PLATFORM=<bool>: 无论是否为多平台输出，都选择确定性输出
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

在 Dockerfile 参考文档 中了解更多关于内置构建参数的信息。

附加构建上下文 (--build-context)

--build-context=name=VALUE

使用指定的内容定义额外的构建上下文。在 Dockerfile 中，当使用 FROM name 或 --from=name 时可以访问该上下文。 当 Dockerfile 定义了同名阶段时，它会被覆盖。

该值可以是本地源目录、 本地 OCI 布局兼容目录、容器镜像（带有 docker-image:// 前缀）、Git 或 HTTP URL。

将 alpine:latest 替换为固定的一个：

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

暴露第二个本地源目录：

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .

# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /

使用 OCI 布局目录作为构建上下文

从本地 符合OCI规范的目录 获取镜像，可以通过标签或摘要：

$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>

# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /

FROM foo

OCI 布局目录必须符合 OCI 布局规范。 您可以使用标签或精确摘要来引用布局中的镜像。

覆盖已配置的构建器实例 (--builder)

与 buildx --builder相同。

为构建使用外部缓存源 (--cache-from)

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

为构建使用外部缓存源。支持的类型包括 registry、 local、gha 和 s3。

  • registry 源 可以从缓存清单或注册表上的（特殊）镜像配置导入缓存。
  • local 源 可以从先前使用 --cache-to 导出的本地文件导入缓存。
  • gha 源 可以通过 GitHub 仓库中的 --cache-to 从先前导出的缓存导入缓存
  • s3 源 可以从您的 S3 存储桶中使用 --cache-to 从先前导出的缓存中导入缓存

如果未指定类型，则使用 registry 导出器及指定的引用。

docker 驱动程序当前仅支持从注册表导入构建缓存。

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
$ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket .

关于缓存导出器和可用属性的更多信息： https://github.com/moby/buildkit#export-cache

调用前端方法 (--call)

--call=[build|check|outline|targets]

BuildKit 前端可以通过前端方法支持构建的替代执行模式。前端方法是一种改变或扩展构建调用行为的方式，例如，它允许您检查、验证构建或从构建中生成替代输出。

--call 的 docker buildx build 标志允许您指定要执行的前端方法。如果未指定此标志，则默认执行构建并评估 构建检查。

对于 Dockerfiles，可用的方法有：

命令描述
build (默认)执行构建并评估当前构建目标的构建检查。
check评估整个 Dockerfile 或选定目标的构建检查，而不执行构建。
outline显示您可以为目标设置的构建参数及其默认值。
targets列出 Dockerfile 中的所有构建目标。
subrequests.describe列出当前前端支持的所有前端方法。

请注意，其他前端可能会实现这些或其他方法。 要查看您正在使用的前端可用的方法列表， 请使用 --call=subrequests.describe。

$ docker buildx build -q --call=subrequests.describe .

NAME                 VERSION DESCRIPTION
outline              1.0.0   List all parameters current build target supports
targets              1.0.0   List all targets current build supports
subrequests.describe 1.0.0   List available subrequest types

描述

--call=targets 和 --call=outline 方法包含对构建目标和参数的描述（如果可用）。 描述是根据 Dockerfile 中的注释生成的。在 FROM 指令前一行的注释会成为构建目标的描述，而 在 ARG 指令前的注释则是构建参数的描述。 注释必须以阶段名称或参数名称开头，例如：

# syntax=docker/dockerfile:1

# GO_VERSION sets the Go version for the build
ARG GO_VERSION=1.22

# base-builder is the base stage for building the project
FROM golang:${GO_VERSION} AS base-builder

当您运行 docker buildx build --call=outline 时，输出包含以下描述：

$ docker buildx build -q --call=outline .

TARGET:      base-builder
DESCRIPTION: is the base stage for building the project

BUILD ARG    VALUE   DESCRIPTION
GO_VERSION   1.22    sets the Go version for the build

有关如何编写 Dockerfile 文档字符串的更多示例， 请查看 Docker 文档的 Dockerfile。

调用: check (--check)

check 方法在不执行构建的情况下评估构建检查。--check 标志是 --call=check 的便捷简写。在开始构建之前，使用 check 方法验证构建配置。

$ docker buildx build -q --check https://github.com/docker/docs.git

WARNING: InvalidBaseImagePlatform
Base image wjdp/htmltest:v0.17.0 was pulled with platform "linux/amd64", expected "linux/arm64" for current build
Dockerfile:43
--------------------
  41 |         "#content/desktop/previous-versions/*.md"
  42 |
  43 | >>> FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test
  44 |     WORKDIR /test
  45 |     COPY --from=build /out ./public
--------------------

使用 --check 而不指定目标将评估整个 Dockerfile。 如果要评估特定目标，请使用 --target 标志。

调用: outline

outline 方法打印指定目标的名称（如果未指定 --target，则为默认目标），以及该目标使用的构建参数及其默认值（如果已设置）。

下面的示例显示了默认目标 release 及其构建参数：

$ docker buildx build -q --call=outline https://github.com/docker/docs.git

TARGET:      release
DESCRIPTION: is an empty scratch image with only compiled assets

BUILD ARG          VALUE     DESCRIPTION
GO_VERSION         1.22      sets the Go version for the base stage
HUGO_VERSION       0.127.0
HUGO_ENV                     sets the hugo.Environment (production, development, preview)
DOCS_URL                     sets the base URL for the site
PAGEFIND_VERSION   1.1.0

这意味着可以使用以下构建参数配置 release 目标：

$ docker buildx build \
  --build-arg GO_VERSION=1.22 \
  --build-arg HUGO_VERSION=0.127.0 \
  --build-arg HUGO_ENV=production \
  --build-arg DOCS_URL=https://example.com \
  --build-arg PAGEFIND_VERSION=1.1.0 \
  --target release https://github.com/docker/docs.git

调用: targets

targets 方法列出了 Dockerfile 中的所有构建目标。这些是 您可以使用 --target 标志构建的阶段。它还指出了 默认目标，即当您未指定目标时将构建的目标。

$ docker buildx build -q --call=targets https://github.com/docker/docs.git

TARGET            DESCRIPTION
base              is the base stage with build dependencies
node              installs Node.js dependencies
hugo              downloads and extracts the Hugo binary
build-base        is the base stage for building the site
dev               is for local development with Docker Compose
build             creates production builds with Hugo
lint              lints markdown files
test              validates HTML output and checks for broken links
update-modules    downloads and vendors Hugo modules
vendor            is an empty stage with only vendored Hugo modules
build-upstream    builds an upstream project with a replacement module
validate-upstream validates HTML output for upstream builds
unused-media      checks for unused graphics and other media
pagefind          installs the Pagefind runtime
index             generates a Pagefind index
test-go-redirects checks that the /go/ redirects are valid
release (default) is an empty scratch image with only compiled assets

将构建缓存导出到外部缓存目标 (--cache-to)

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

将构建缓存导出到外部缓存目标。支持的类型有 registry、local、inline、gha 和 s3。

docker 驱动程序仅支持使用 inline 和 local 缓存后端的缓存导出。

属性键：

  • mode - 指定随缓存导出的层数。min 表示仅导出最终构建阶段中已有的层，max 表示导出所有阶段的层。元数据始终针对整个构建导出。
$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
$ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket .

关于缓存导出器和可用属性的更多信息： https://github.com/moby/buildkit#export-cache

使用自定义父 cgroup (--cgroup-parent)

当您使用 --cgroup-parent 选项运行 docker buildx build 时， 守护进程会使用 相应的 docker run 标志 来运行构建中使用的容器。

指定 Dockerfile (-f, --file)

$ docker buildx build -f <filepath> .

指定要使用的 Dockerfile 的文件路径。 如果未指定，则默认使用构建上下文根目录下名为 Dockerfile 的文件。

要从标准输入读取 Dockerfile，您可以使用 - 作为 --file 的参数。

$ cat Dockerfile | docker buildx build -f - .

将单平台构建结果加载到 docker images (--load)

--output=type=docker 的简写。会自动将单平台构建结果加载到 docker images。

将构建结果元数据写入文件 (--metadata-file)

要输出构建元数据（例如镜像摘要），请传递 --metadata-file 标志。 元数据将作为 JSON 对象写入指定的文件。指定文件的目录必须已存在且可写。

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json

{
  "buildx.build.provenance": {},
  "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
  "buildx.build.warnings": {},
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

注意

构建记录 来源 (buildx.build.provenance) 默认包含最小来源。设置 BUILDX_METADATA_PROVENANCE 环境变量以自定义此行为：

  • min 设置最小来源（默认）。
  • max 设置完整来源。
  • disabled, false 或 0 不设置任何来源。

注意

构建警告（buildx.build.warnings）默认不包含。将 BUILDX_METADATA_WARNINGS 环境变量设置为 1 或 true 以包含它们。

设置构建期间 RUN 指令的网络模式 (--network)

网络模式的可用选项包括：

  • default (默认): 在默认网络中运行。
  • none: 无网络访问权限运行。
  • host: 在宿主机网络环境中运行。

在 Dockerfile 参考中查找更多详细信息。

忽略特定阶段的构建缓存 (--no-cache-filter)

--no-cache-filter 让您可以指定多阶段 Dockerfile 中的一个或多个阶段，以忽略其构建缓存。若要指定多个阶段，请使用逗号分隔的语法：

$ docker buildx build --no-cache-filter stage1,stage2,stage3 .

例如，以下 Dockerfile 包含四个阶段：

  • base
  • install
  • test
  • release
# syntax=docker/dockerfile:1

FROM oven/bun:1 AS base
WORKDIR /app

FROM base AS install
WORKDIR /temp/dev
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=bun.lockb,target=bun.lockb \
    bun install --frozen-lockfile

FROM base AS test
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
RUN bun test

FROM base AS release
ENV NODE_ENV=production
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
ENTRYPOINT ["bun", "run", "index.js"]

要忽略 install 阶段的缓存：

$ docker buildx build --no-cache-filter install .

要忽略 install 和 release 阶段的缓存：

$ docker buildx build --no-cache-filter install,release .

--no-cache-filter 标志的参数必须是阶段的名称。

设置构建结果的导出动作 (-o, --output)

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

设置构建结果的导出操作。使用 docker 构建驱动时的默认输出，是导出到本地镜像存储的容器 镜像。--output 标志使此步骤可配置，并允许将结果直接导出到客户端文件系统、 OCI 镜像 tarball、注册表等。

具有 docker 驱动程序的 Buildx 仅支持 local、tarball 和 image 导出器。docker-container 驱动程序支持所有导出器。

如果你仅指定一个文件路径作为 --output 的参数，Buildx 使用本地导出器。如果值为 -，Buildx 使用 tar 导出器并将输出写入 stdout。

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - . > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

您可以通过重复该标志来导出多个输出。

支持的导出类型有：

local

local 导出类型将所有结果文件写入客户端上的一个目录中。新文件将归当前用户所有。在多平台构建中，所有结果将按其平台放入子目录中。

属性键：

  • dest - 文件将被写入的目标目录

有关更多信息，请参阅 本地和 tar 导出器。

tar

tar 导出类型将所有结果文件作为单个 tarball 写入客户端。 在多平台构建中，所有结果将按平台放入子目录中。

属性键：

  • dest - 将写入 tar 包的目标路径。“-” 表示写入标准输出。

有关更多信息，请参阅 本地和 tar 导出器。

oci

oci 导出类型将结果镜像或清单列表作为 OCI 镜像 布局 tarball 写入客户端。

属性键：

  • dest - 将写入 tar 包的目标路径。“-” 表示写入标准输出。

有关更多信息，请参阅 OCI 和 Docker 导出器。

docker

docker 导出类型将单平台结果镜像作为 Docker 镜像规范 tarball 写入客户端。由此导出器创建的 tarball 也兼容 OCI。

Docker 引擎中的默认镜像存储不支持加载多平台 镜像。您可以启用 containerd 镜像存储，或者推送多平台镜像 即直接推送到注册表，请参阅 registry。

属性键：

  • dest - 将写入 tar 包的目标路径。如果未指定，tar 包将自动加载到本地镜像存储中。
  • context - 用于导入结果的 Docker 上下文名称

有关更多信息，请参阅 OCI 和 Docker 导出器。

image

image 导出器将构建结果写入为镜像或清单列表。当使用 docker 驱动程序时，镜像将出现在 docker images 中。或者，可以通过指定属性将镜像自动推送到注册表。

属性键：

  • name - 新镜像的名称（引用）。
  • push - 布尔值，用于自动推送镜像。

如需更多信息，请参阅 镜像和仓库导出器。

registry

registry 导出器是 type=image,push=true 的快捷方式。

如需更多信息，请参阅 镜像和仓库导出器。

设置构建的目标平台 (--platform)

--platform=value[,value]

设置构建的目标平台。Dockerfile 中所有不带 --platform 标志的 FROM 命令都将拉取该平台的基础镜像，该值也将成为结果镜像的平台。

默认值是运行构建的 BuildKit 守护进程的平台。 该值的格式为 os/arch 或 os/arch/variant。例如， linux/amd64 或 linux/arm/v7。此外，--platform 标志还支持 一个特殊的 local 值，它指示 BuildKit 使用调用构建的 BuildKit 客户端的平台。

当将 docker-container 驱动程序与 buildx 一起使用时，此标志可以接受多个以逗号分隔的值作为输入。对于多个值，结果将为所有指定的平台构建，并合并到一个单一的清单列表中。

如果 Dockerfile 需要调用 RUN 命令，构建器需要为指定平台提供运行时支持。在纯净设置中，您只能执行系统架构对应的 RUN 命令。如果您的内核支持 binfmt_misc 辅助架构的启动器，buildx 将自动识别它们。Docker Desktop 版本自带为 arm64 和 arm 架构自动配置的 binfmt_misc。您可以通过运行 docker buildx inspect --bootstrap 来查看当前构建器实例支持的运行时平台。

在 Dockerfile 中，你可以通过 TARGETPLATFORM 构建参数访问当前平台值。有关自动平台参数变体的完整描述，请参阅 Dockerfile 参考。

您可以在 containerd 源代码 中找到平台说明符的格式定义。

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

设置进度输出的类型 (--progress)

--progress=VALUE

设置进度输出的类型（auto、plain、tty、rawjson）。使用 plain 显示容器输出（默认值为 auto）。

注意

您也可以使用 BUILDKIT_PROGRESS 环境变量来设置其值。

下面的示例在构建过程中使用 plain 输出：

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

注意

另请查看 BUILDKIT_COLORS 环境变量，用于修改终端输出的颜色。

rawjson 输出将来自 BuildKit 的求解状态事件编组为 JSON 行。 此模式旨在供外部程序读取。

创建来源证明 (--provenance)

--attest=type=provenance 的简写形式，用于为构建结果配置来源证明。例如，--provenance=mode=max 可用作 --attest=type=provenance,mode=max 的缩写。

此外，--provenance 可以与布尔值一起使用，以启用或禁用来源证明。例如，--provenance=false 禁用所有来源证明，而 --provenance=true 启用所有来源证明。

默认情况下，会为构建结果创建一个最小化的来源证明。请注意，Docker 引擎中的默认镜像存储不支持证明。如果您使用默认镜像存储，来源证明仅对直接推送到注册表的镜像持久保存。或者，您可以切换到使用 containerd 镜像存储。

有关来源证明的更多信息，请参阅 此处。

将构建结果推送到镜像仓库 (--push)

--output=type=registry 的简写。会自动将构建结果推送到仓库。

创建 SBOM 证明 (--sbom)

是 --attest=type=sbom 的简写，用于为构建结果配置 SBOM 证明。例如，--sbom=generator=<user>/<generator-image> 可用作 --attest=type=sbom,generator=<user>/<generator-image> 的缩写。

此外，--sbom 可用于布尔值以启用或禁用 SBOM 证明。例如，--sbom=false 禁用所有 SBOM 证明。

请注意，Docker Engine 中的默认镜像存储不支持证明（attestations）。如果您使用默认镜像存储，来源证明（Provenance attestations）仅对直接推送到注册表的镜像保留。或者，您可以切换到使用 containerd 镜像存储。

欲了解更多信息，请参阅 此处。

向构建公开的机密 (--secret)

--secret=[type=TYPE[,KEY=VALUE]

将密钥（身份验证凭据、令牌）暴露给构建。 密钥可以通过 Dockerfile 中的 RUN --mount=type=secret 挂载到构建中。 有关如何使用构建密钥的更多信息，请参阅 Build secrets。

支持的类型有：

Buildx 尝试自动检测 type（如果未设置）。如果设置了与 id 具有相同键的环境变量，则 Buildx 使用 type=env，且变量值即为该密钥。如果未设置此类环境变量，且 type 未设置，则 Buildx 回退到 type=file。

type=file

从文件获取构建机密信息。

type=file 概要
$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .
type=file 个属性
密钥描述默认
id密钥的 ID。不适用（此键为必填项）
src, source包含密钥值的文件的文件路径（绝对路径或相对于当前工作目录的路径）。id 如果未设置。
type=file 使用量

在下面的例子中，type=file 被自动检测到，因为没有设置匹配 aws（即 ID）的环境变量。

$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

# syntax=docker/dockerfile:1
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...

type=env

从环境变量获取构建秘密。

type=env 概要
$ docker buildx build --secret [type=env,]id=<ID>[,env=<VARIABLE>] .
type=env 个属性
密钥描述默认
id密钥的 ID。不适用（此键为必填项）
env, src, source用于获取密钥的环境变量。id 如果未设置。
type=env 使用量

在下面的示例中，type=env 被自动检测到，因为设置了匹配 id 的环境变量。

$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN,env=SECRET_TOKEN \
  yarn run test

在以下示例中，构建参数 SECRET_TOKEN 被设置为包含环境变量 API_KEY 的值。

$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .

你也可以使用 src 或 source 来指定环境变量的名称：

$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .

注意

指定环境变量名称为 src 或 source 时，您必须显式设置 type=env，否则 Buildx 会假定密钥为 type=file，并查找名为 src 或 source 的文件（在这种情况下，是一个名为 API_KEY 的文件，相对于执行 docker buildx build 命令的位置。

构建容器的共享内存大小 (--shm-size)

设置在使用RUN指令时为构建容器分配的共享内存大小。

格式为 <number><unit>。 number 必须大于 0。单位是可选的，可以是 b（字节）、k（千字节）、m（兆字节）或 g（千兆字节）。如果省略单位，系统将使用字节。

注意

在大多数情况下，建议让构建器自动确定适当的配置。只有在复杂构建场景需要特定性能调优时，才应考虑手动调整。

要暴露给构建的 SSH 代理套接字或密钥 (--ssh)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

当 Dockerfile 中的某些命令需要特定的 SSH 身份验证（例如，克隆私有仓库）时，这会很有用。

--ssh 将 SSH agent 套接字或密钥暴露给构建环境，并可与 RUN --mount=type=ssh 挂载 一起使用。

使用 SSH 代理套接字访问 Gitlab 的示例：

# syntax=docker/dockerfile:1
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 -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

标记镜像 (-t, --tag)

$ docker buildx build -t docker/apache:2.0 .

此示例的构建方式与上一个示例相同，但它随后会为生成的镜像打标签。仓库名称将为 docker/apache，标签为 2.0。

阅读更多关于有效标签的信息。

您可以为镜像应用多个标签。例如，您可以将 latest 标签应用于新构建的镜像，并添加另一个引用特定版本的标签。

例如，要将镜像同时标记为 docker/fedora-jboss:latest 和 docker/fedora-jboss:v2.1，请使用以下命令：

$ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 .

指定目标构建阶段 (--target)

在使用多阶段构建 Dockerfile 时，使用 --target 选项按名称指定一个中间构建阶段作为结果镜像的最终阶段。构建器将跳过目标阶段之后的命令。

FROM debian AS build-env
# ...

FROM alpine AS production-env
# ...
$ docker buildx build -t mybuildimage --target build-env .

设置 ulimit (--ulimit)

--ulimit 在使用 RUN 指令时会覆盖构建容器的默认 ulimit，并使用软限制和硬限制指定，例如： <type>=<soft limit>[:<hard limit>]：

$ docker buildx build --ulimit nofile=1024:1024 .

注意

如果您未提供 hard limit，则这两个值都使用 soft limit。如果未设置 ulimits，它们将从守护进程上设置的默认 ulimits 继承。

注意

在大多数情况下，建议让构建器自动确定适当的配置。只有在复杂构建场景需要特定性能调优时，才应考虑手动调整。