Docker BuildX 构建

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

描述

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

选项

选择	违约	描述
`--add-host`		添加自定义主机到 IP 映射（格式：`host:ip`)
`--allow`		允许额外的特权授权（例如，`network.hostsecurity.insecure`)
`--annotation`		向镜像添加注释
`--attest`		认证参数（格式：`type=sbom,generator=image`)
`--build-arg`		设置构建时变量
`--build-context`		其他构建上下文（例如，name=path）
`--cache-from`		外部缓存源（例如、`user/app:cachetype=local,src=path/to/dir`)
`--cache-to`		缓存导出目标（例如，`user/app:cachetype=local,dest=path/to/dir`)
`--call`	`build`	Set 评估 build 的方法（，，`checkoutlinetargets`)
`--cgroup-parent`		在构建过程中为说明设置父 cgroup`RUN`
`--check`		的简写`--call=check`
`--detach`		实验性的（CLI）分离 buildx 服务器（仅在 linux 上受支持）
`-f, --file`		Dockerfile 的名称（默认值：`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`		设置用于生成的目标平台
`--progress`	`auto`	设置进度输出的类型（、）。使用 plain 显示容器输出`autoplainttyrawjson`
`--provenance`		的简写`--attest=type=provenance`
`--pull`		始终尝试拉取所有引用的镜像
`--push`		的简写`--output=type=registry`
`-q, --quiet`		成功时禁止生成输出并打印镜像 ID
`--root`		实验性的（CLI）指定要连接的服务器的根目录
`--sbom`		的简写`--attest=type=sbom`
`--secret`		Secret 公开给 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`		设置要生成的目标生成阶段
`--ulimit`		Ulimit 选项

例子

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

您可以使用一个或更多标志。此示例为名为和的主机添加静态地址：/etc/hosts--add-hostmy-hostnamemy_hostname_v6

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

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

$ 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，则镜像清单将进行注释。以下示例将注释添加 image 索引，而不是清单：foo=bar

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

您可以指定多个类型，用逗号（，）分隔以添加注释添加到多个镜像组件。以下示例将注释添加到 image index、descriptors、manifests：foo=bar

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

您还可以在方括号（）中指定平台限定符 type 前缀，以将注释应用于清单子集，其中包含匹配平台。以下示例仅将注释添加到带有平台的清单：[os/arch]foo=barlinux/amd64

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

platform 限定符不支持通配符;您无法指定类型前缀，例如仅向具有 OS 平台的清单添加注释。manifest[linux/*]linux

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

创建证明（--attest）

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

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

sbom- 软件物料清单。
用于在构建时为镜像生成 SBOM。或者，您可以使用 --sbom 简写。--attest=type=sbom
有关更多信息，请参阅此处。
provenance- SLSA 起源
用于生成镜像的来源 build-time 的 build 时。或者，您可以使用 --provenance 简写。--attest=type=provenance
默认情况下，将为构建创建最小出处证明 result，该结果将仅针对推送到 registry 的镜像附加。
有关更多信息，请参阅此处。

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

--allow=ENTITLEMENT

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

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

对于要启用的权利，BuildKit 守护进程还需要允许它们 with（参见创建 --buildkitd-flags）。--allow-insecure-entitlement

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

其他构建上下文（--build-context）

--build-context=name=VALUE

使用指定内容定义其他构建上下文。在 Dockerfile 中，可以在 WHEN 或 IS IS ACCESS 上下文。当 Dockerfile 定义具有相同名称的阶段时，它将被覆盖。FROM name--from=name

该值可以是本地源目录、本地 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 布局规范。您可以使用标签或确切摘要在布局中引用镜像。

使用外部缓存源进行构建（--cache-from）

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

使用外部缓存源进行构建。支持的类型包括、和。registrylocalghas3

Registry 源可以从注册表。
local source 可以从以前使用 . 导出的本地文件导入缓存。--cache-to
GHA 源可以从之前导出的缓存中导入缓存，并在 GitHub 存储库--cache-to
S3 源可以从以前导出的缓存中导入缓存，并在您的 S3 存储桶--cache-to

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

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 方法。前端方法是更改或扩展行为，例如，允许您检查、验证、或从构建生成替代输出。

的标志允许您指定前端方法。如果未指定此标志，则默认为执行生成和评估生成检查。--calldocker 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=outline 方法包括构建目标和参数的描述（如果可用）。描述是根据 Dockerfile 中的注释生成的。对行成为构建目标的描述，而指令前的注释 build 参数的描述。这 comment 必须以 stage 或 argument 的名称开头，例如：FROMARG

# 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

当您运行时，输出包括 descriptions，如下所示：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）

该方法在不执行构建的情况下评估构建检查。flag 是 .在开始构建之前，使用该方法验证构建配置。check--check--call=checkcheck

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

在不指定目标的情况下使用会评估整个 Dockerfile。如果要评估特定目标，请使用 flag.--check--target

调用：outline

该方法打印指定目标的名称（或默认的 target（如果未指定）以及 target consumes 及其默认值（如果已设置）。outline--target

以下示例显示了默认目标及其 build 参数：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

这意味着可以使用以下 build 参数配置目标：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

该方法列出了 Dockerfile 中的所有构建目标。这些是您可以使用 FLAG 构建的阶段。它还指示 default 目标，这是在您未指定目标。targets--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]]

将构建缓存导出到外部缓存目标。支持的类型包括、、和。registrylocalinlineghas3

Registry Type 将 Build Cache 导出到 Registry 中的 Cache 清单。
本地类型导出 cache 复制到客户端的本地目录。
inline 类型将缓存元数据写入镜像配置。
gha 类型通过 GitHub Actions Cache 服务 API 导出缓存。
S3 类型导出 cache 添加到 S3 存储桶。

该驱动程序仅支持使用和 cache 后端的缓存导出。dockerinlinelocal

属性键：

mode- 指定与缓存一起导出的图层数。仅在 on exports layers already in final build stage（导出已处于最终构建阶段的层），导出所有阶段。始终为整个构建导出元数据。minmax

$ 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 Run 标志运行构建中使用的容器。docker buildx build--cgroup-parent

指定 Dockerfile （-f， --file）

$ docker buildx build -f <filepath> .

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

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

$ cat Dockerfile | docker buildx build -f - .

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

--output=type=docker 的简写。将自动加载 single-platform build 结果设置为 .docker images

将构建结果元数据写入文件（--metadata-file）

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

$ 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"
}

注意
默认情况下，Build record provenance （）包含最小出处。设置环境变量以自定义此行为：buildx.build.provenanceBUILDX_METADATA_PROVENANCE
min设置最小出处（默认）。
max设置完全出处。
disabled，或者不设置任何出处。false0

注意
默认情况下，不包含生成警告（）。将环境变量设置为或包括它们。buildx.build.warningsBUILDX_METADATA_WARNINGS1true

在构建过程中设置 RUN 指令的联网模式（--network）

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

default（默认）：在默认网络中运行。
none：在没有网络访问权限的情况下运行。
host：在主机的网络环境中运行。

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

忽略特定阶段的构建缓存（--no-cache-filter）

允许您指定多阶段的一个或多个阶段应忽略其构建缓存的 Dockerfile。要指定多个阶段，使用逗号分隔的语法：--no-cache-filter

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

要忽略缓存 and 阶段：installrelease

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

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

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

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

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

带有驱动程序的 Buildx 仅支持本地、tarball 和镜像导出器。该驱动程序支持所有导出器。dockerdocker-container

如果只指定 filepath 作为的参数，则 Buildx 使用本地导出器。如果值为，则 Buildx 使用导出器并写入输出到 stdout。--output-tar

$ 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
tar
oci
docker
image
registry

`local`

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

属性键：

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

`tar`

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

属性键：

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

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

`oci`

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

属性键：

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

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

`docker`

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

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

属性键：

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

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

`image`

导出器将构建结果写入镜像或清单列表。什么时候使用 Driver 时，镜像将显示在中。（可选）镜像可以通过指定属性自动推送到注册表。imagedockerdocker images

属性键：

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

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

`registry`

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

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

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

--platform=value[,value]

设置生成的目标平台。Dockerfile 中的所有命令如果没有自己的标志，则会为此平台拉取基础镜像，而此值也将是结果镜像的平台。FROM--platform

默认值是运行生成的 BuildKit 守护程序的平台。该值采用或的形式。例如，或 .此外，该标志还支持一个特殊的值，它告诉 BuildKit 使用 BuildKit 的平台调用生成的客户端。os/archos/arch/variantlinux/amd64linux/arm/v7--platformlocal

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

如果需要调用命令，则 builder 需要运行时对指定平台的支持。在干净的设置中，您只能为您的系统架构执行命令。如果你的内核支持二级架构的 binfmt_misc 启动器，buildx 会自动获取它们。 Docker Desktop 版本附带自动配置的和架构。您可以查看当前构建器的运行时平台实例支持。DockerfileRUNRUNbinfmt_miscarm64armdocker buildx inspect --bootstrap

在中，您可以通过 build 参数访问当前 platform 值。有关自动平台参数变体的完整说明，请参阅 Dockerfile 参考。DockerfileTARGETPLATFORM

您可以在 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

设置进度输出的类型（、）。用于显示容器 output （默认）。autoplainttyrawjsonplainauto

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

以下示例在构建期间使用 output：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 环境变量以修改终端输出的颜色。

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

创建出处证明（--provenance）

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

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

默认情况下，将为构建创建最小出处证明结果。请注意，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--sbom=false

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

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

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

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

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

支持的类型包括：

type=file
type=env

如果未设置，Buildx 会尝试自动检测。如果环境变量，则 Buildx 使用 variable value 成为 secret。如果未设置此类环境变量，并且未设置，则 Buildx 将回退到。typeidtype=envtypetype=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=文件`使用情况

在以下示例中，会自动检测到，因为没有环境变量数学运算（ID）已设置。type=fileaws

$ 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`, ,`srcsource`	要从中获取密钥的环境变量。	`id`如果未设置。

`type=env` 用法

在以下示例中，会自动检测到环境变量匹配。type=envid

$ 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 参数设置为 contains 环境变量的值。SECRET_TOKENAPI_KEY

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

您还可以使用或指定环境变量的名称：srcsource

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

注意
使用或指定环境变量名称，您是 required 显式设置，否则 Buildx 会假设 secret 是，并查找名称为或（在在本例中，名为 relative 的文件srcsourcetype=envtype=filesrcsourceAPI_KEYdocker buildx build

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

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

格式为 . 必须大于。单位为可选，可以是（bytes）、（KB）、（MB）或（GB）。如果省略该单位，系统将使用字节。<number><unit>number0bkmg

注意
在大多数情况下，建议让 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 .

此示例的构建方式与上一个示例相同，但它随后会标记生成的镜像。存储库名称将为和 tag 。docker/apache2.0

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

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

例如，要将镜像同时标记为和，请使用以下内容：docker/fedora-jboss:latestdocker/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使用指令时覆盖 build 容器的默认 ulimit，并指定软限制和硬限制，如下所示：，例如：RUN<type>=<soft limit>[:<hard limit>]

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

注意
如果您不提供，则使用对于这两个值。如果未设置，则它们继承自守护程序上的默认设置。hard limitsoft limitulimitsulimits

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