切换语言

Docker BuildX 构建

描述开始构建
用法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设置评估 build 的方法 （check,outline,targets)
--cgroup-parent为RUN构建过程中的说明
--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
--root实验性的 （CLI）指定要连接的服务器的根目录
--sbom的简写--attest=type=sbom
--secretSecret 公开给 build （格式：id=mysecret[,src=/local/secret])
--server-config实验性的 （CLI）指定 buildx 服务器配置文件（仅在启动新服务器时使用）
--shm-size构建容器的共享内存大小
--ssh要向 build 公开的 SSH 代理套接字或密钥（格式：default|<id>[=<socket>|<key>[,<key>]])
-t, --tag名称和标记（可选）（格式：name:tag)
--target设置要生成的目标生成阶段
--ulimitUlimit 选项

例子

将条目添加到容器主机文件 （--add-host）

您可以将其他主机添加到构建容器的/etc/hostsfile 使用一个 或更多--add-host标志。此示例为名为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 .

如果您需要构建连接到主机上运行的服务，则可以使用 特别版host-gateway的值--add-host.在以下示例中， 构建容器解析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 .

您可以选择添加类型前缀以指定注释的级别。由 default，则镜像清单将进行注释。以下示例将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]） 在 type 前缀，以将注释应用于清单子集，其中包含 匹配平台。以下示例将foo=barannotation only 设置为 带有linux/amd64平台：

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

platform 限定符不支持通配符;您无法指定类型 前缀，如manifest[linux/*]仅向具有linux作为 OS 平台。

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

创建证明 （--attest）

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

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

  • sbom- 软件物料清单。

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

    有关更多信息，请参阅此处。

  • provenance- SLSA 起源

    用--attest=type=provenance为 build-time 的 build 时。或者，您可以使用--provenance速记.

    默认情况下，将为构建创建最小出处证明 result，该结果将仅针对推送到 registry 的镜像附加。

    有关更多信息，请参阅此处。

允许额外的特权授权 （--allow）

--allow=ENTITLEMENT

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

  • network.host- 允许使用主机网络执行。
  • security.insecure- 允许在没有 Sandbox 的情况下执行。请参阅相关的 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）

您可以使用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 .

此标志允许您传递构建时变量，这些变量是 像常规环境变量一样在RUN指示 Dockerfile 文件。这些值不会保留在中间或最终镜像中 喜欢ENV价值观可以。您必须添加--build-arg对于每个 build 参数。

使用此标志不会改变您在构建过程回显ARG行 Dockerfile 文件。

有关使用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文档了解更多信息。

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

  • 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源可以从 Cache 清单或 （特殊） 镜像配置导入缓存 注册表。
  • local源能 从以前使用--cache-to.
  • gha源可以从先前导出的缓存中导入缓存--cache-to在 GitHub 存储库
  • s3源可以从先前导出的缓存中导入缓存--cache-to在 S3 存储桶

如果未指定类型，则registryexporter 与指定的引用一起使用。

dockerdriver 目前仅支持从 registry 导入 build cache。

$ 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 前端可以支持替代的构建执行模式， 使用 frontend 方法。前端方法是更改或扩展 行为，例如，允许您检查、验证、 或从构建生成替代输出。

这--call的标志docker buildx build允许您指定前端 方法。如果未指定此标志，则默认为 执行生成和评估生成检查。

对于 Dockerfile，可用的方法有：

命令描述
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=outlinemethods 包括构建目标和参数的描述（如果可用）。 描述是根据 Dockerfile 中的注释生成的。对 行FROMinstruction 变为构建目标的描述，而 在ARG指令 build 参数的描述。这 comment 必须以 stage 或 argument 的名称开头，例如：

# 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，则输出包括 descriptions，如下所示：

$ 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）

这checkmethod 在不执行构建的情况下评估构建检查。这--checkflag 是--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

这outlinemethod 打印指定目标的名称（或默认的 target，如果--target未指定），并且目标 consumes 及其默认值（如果已设置）。

以下示例显示了默认目标release及其 build 参数：

$ 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

这意味着releasetarget 可以使用以下 build 参数进行配置：

$ 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

这targetsmethod 列出了 Dockerfile 中的所有构建目标。这些是 您可以使用--target旗。它还指示 default 目标，这是在您未指定 目标。

$ 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和localcache 后端。

属性键：

  • mode- 指定与缓存一起导出的图层数。min仅在 on 导出已处于最终构建阶段的层，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）

当您运行docker buildx build使用--cgroup-parent选择 守护程序使用相应docker run旗.

指定 Dockerfile （-f， --file）

$ docker buildx build -f <filepath> .

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

要从 stdin 读取 Dockerfile，您可以用作---file.

$ cat Dockerfile | docker buildx build -f - .

将单平台构建结果加载到docker images（--load）

的简写--output=type=docker.将自动加载 single-platform build 结果设置为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-filterflag 必须是阶段的名称。

设置构建结果的导出作 （-o， --output）

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

设置构建结果的导出作。默认输出，当使用docker build 驱动程序，是一个容器 Image 导出到本地镜像存储。这--outputflag 执行此步骤 configurable 允许将结果直接导出到客户端的文件系统，一个 OCI 镜像 tarball、注册表等。

Buildx 与dockerdriver 仅支持 local、tarball 和 image 导出器。这docker-containerdriver 支持所有导出器。

如果仅指定 filepath 作为--output，Buildx 使用 本地导出器。如果值为 ，则 Buildx 使用-tarexporter 和 writes 输出到 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

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

属性键：

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

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

tar

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

属性键：

  • dest- 将写入 tarball 的目标路径。“-” 写入 stdout。

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

oci

这ociexport 类型将结果镜像或清单列表写入 OCI 镜像 layout tarball 的 tar 包。

属性键：

  • dest- 将写入 tarball 的目标路径。“-” 写入 stdout。

有关详细信息，请参阅 OCI 和 Docker 导出程序。

docker

这dockerexport 类型将单平台结果镜像写入 Docker 镜像 规范 tarball 的 tarball 中。此导出程序创建的 tarball 也与 OCI 兼容。

Docker Engine 中的默认镜像存储不支持多平台加载 镜像。您可以启用 containerd 镜像存储，或推送多平台镜像 是直接推送到 Registry 中，请参阅registry.

属性键：

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

有关详细信息，请参阅 OCI 和 Docker 导出程序。

image

这imageexporter 将构建结果写入镜像或清单列表。什么时候 用docker驱动程序中，镜像将出现在docker images.（可选）镜像 可以通过指定属性自动推送到注册表。

属性键：

  • name- 新镜像的名称（引用）。
  • push- Boolean 自动推送镜像。

有关更多信息，请参阅镜像和注册表导出器。

registry

这registryexporter 是type=image,push=true.

有关更多信息，请参阅镜像和注册表导出器。

设置构建的目标平台 （--platform）

--platform=value[,value]

设置生成的目标平台。都FROM命令 没有自己的--platformflag 将拉取此平台的基础镜像，并且 此值也将是结果镜像的平台。

默认值是运行生成的 BuildKit 守护程序的平台。 该值采用os/arch或os/arch/variant.例如linux/amd64或linux/arm/v7.此外，--platformflag 还支持 特别的local值，它告诉 BuildKit 使用 BuildKit 的平台 调用生成的客户端。

使用docker-containerdriver 替换为buildx，此标志可以接受多个 值作为输入，以逗号分隔。如果有多个值，结果将为 为所有指定的平台构建，并合并到一个清单中 列表。

如果Dockerfile需要调用RUN命令，则构建器需要运行时 对指定平台的支持。在干净的设置中，您只能执行RUN命令。 如果您的内核支持binfmt_misc启动器，BuildX 会自动拾取它们。 Docker Desktop 版本附带binfmt_misc自动配置arm64和arm架构。您可以查看当前构建器的运行时平台 实例支持docker buildx inspect --bootstrap.

在Dockerfile中，您可以通过TARGETPLATFORMbuild 参数。有关自动平台参数变体的完整说明，请参阅 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显示容器 output（默认auto).

注意

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

以下示例使用plainoutput 中执行

$ 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环境变量，用于修改终端输出的颜色。

这rawjsonoutput 将 BuildKit 中的 solve 状态事件封送到 JSON 行。 此模式设计为由外部程序读取。

创建出处证明 （--provenance）

的简写--attest=type=provenance，用于配置 生成结果的 Provenance 证明。例如--provenance=mode=max可以用作--attest=type=provenance,mode=max.

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

默认情况下，将为构建创建最小出处证明 结果。请注意，Docker Engine 中的默认镜像存储不支持 证明。来源证明仅对直接推送的镜像保留 到 registry（如果使用默认镜像存储）。或者，您也可以将 使用 containerd 镜像存储。

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

将构建结果推送到注册表 （--push）

的简写--output=type=registry.会自动推送 build 结果复制到注册表中。

创建 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 中的默认镜像存储不支持 证明。来源证明仅对直接推送的镜像保留 到 registry（如果使用默认镜像存储）。或者，您也可以将 使用 containerd 镜像存储。

有关更多信息，请参阅此处。

要向生成公开的密钥 （--secret）

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

向构建公开密钥（身份验证凭证、令牌）。 可以使用RUN --mount=type=secretmount 在 Dockerfile 中。 有关如何使用构建密钥的更多信息，请参阅构建密钥。

支持的类型包括：

Buildx 尝试检测type如果未设置，则自动。如果环境 变量，其键与id设置，则 Buildx 使用type=env和 variable value 成为 secret。如果未设置此类环境变量，并且type未设置，则 Buildx 会回退到type=file.

type=file

从文件获取生成密钥。

type=file概要
$ docker buildx build --secret [type=file,]id=<ID>[,src=<FILEPATH>] .
type=file属性
钥匙描述违约
id密钥的 ID。N/A （此密钥是必需的）
src,source包含 secret 值（绝对值或相对于当前工作目录）的文件的文件的 Filepath。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。N/A （此密钥是必需的）
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

在下面的示例中，build 参数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 会假定 secret 是type=file，并查找名称为src或source（在 在这种情况下，一个名为API_KEY相对于docker buildx build命令已执行。

构建容器的共享内存大小 （--shm-size）

设置在使用RUN指示。

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

注意

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

要向 build 公开的 SSH 代理套接字或密钥 （--ssh）

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

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

--ssh向构建公开 SSH 代理套接字或密钥，并且可以与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 .

设置 ulimits （--ulimit）

--ulimit在使用RUN说明，并指定了软限制和硬限制，如下所示：<type>=<soft limit>[:<hard limit>]例如：

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

注意

如果您未提供hard limit这soft limit已使用 对于这两个值。如果没有ulimits设置，则它们继承自 默认的ulimits设置在守护进程上。

注意

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