docker buildx 构建

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

描述

该buildx build命令使用 BuildKit 启动构建。此命令与命令的 UI 类似docker build，并采用相同的标志和参数。

有关大多数标志的文档，请参阅 docker build 文档。本页描述了新标志的子集。

选项

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

例子

创建注释（--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

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

创建证明（--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）

docker build与命令相同 。

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

  • BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>: 触发git context来保留.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和。ghas3

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

如果未指定类型，则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

将构建缓存导出到外部缓存目标 (--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

将单平台构建结果加载到docker镜像（--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",
  "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不设置任何出处。

忽略特定阶段的构建缓存（--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 build所有构建中，通过创建容器映像并将其导出到docker images.buildx使此步骤可配置，允许将结果直接导出到客户端、OCI 图像 tarball、注册表等。

Buildx with dockerdriver 目前仅支持本地、tarball 导出器和图像导出器。docker-container驱动程序支持所有出口商。

如果仅将路径指定为值，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

**笔记 **

从 BuildKit v0.13.0 开始，可以通过重复标志来指定多个输出。

支持的导出类型有：

当地的

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

属性键：

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

柏油

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

属性键：

  • dest- 将写入 tarball 的目标路径。 “-”写入标准输出。

奥西

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

属性键：

  • dest- 将写入 tarball 的目标路径。 “-”写入标准输出。

泊坞窗

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

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

属性键：

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

图像

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

属性键：

  • name- 新图像的名称（参考）。
  • push- 布尔值自动推送图像。

注册表

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

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

--platform=value[,value]

设置构建的目标平台。FROMDockerfile 中没有自己标志的所有命令--platform都将拉取该平台的基础映像，并且该值也将是生成映像的平台。

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

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

如果Dockerfile需要调用RUN命令，构建器需要指定平台的运行时支持。在全新设置中，您只能执行RUN 适合您的系统架构的命令。如果您的内核支持 binfmt_misc 辅助架构的启动器，buildx 将自动选择它们。 Docker 桌面版本附带binfmt_misc自动配置arm64 和arm架构。您可以通过运行来查看当前构建器实例支持哪些运行时平台docker buildx inspect --bootstrap。

在 a 内部，您可以通过构建参数Dockerfile访问当前平台值 。 有关自动平台参数变体的完整说明，TARGETPLATFORM请参阅 docker build 文档。

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

笔记

另请查看我们的 颜色输出控制指南 ，以修改用于将信息输出到终端的颜色。

创建出处证明 (--provenance)

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

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

默认情况下，将为构建结果创建最小来源证明。请注意，Docker Engine 中的默认映像存储不支持证明。如果您使用默认映像存储，则来源证明仅适用于直接推送到注册表的映像。或者，您可以切换到使用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 中的默认映像存储不支持证明。如果您使用默认映像存储，则来源证明仅适用于直接推送到注册表的映像。或者，您可以切换到使用containerd镜像存储。

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

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

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

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

支持的类型有：

Buildx 尝试自动检测type是否未设置。

文件

属性键：

  • id- 秘密的 ID。默认为src路径的基本名称。
  • src, source- 秘密文件名。id如果未设置则使用。
# 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://... ...
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

环境

属性键：

  • id- 秘密的 ID。默认为env名称。
  • env- 秘密环境变量。id如果未设置则使用，否则将查找src,source如果id未设置。
# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN \
  SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

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

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

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

笔记

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

向构建公开的 SSH 代理套接字或密钥 (--ssh)

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

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

--ssh向构建公开 SSH 代理套接字或密钥，并且可以与 RUN --mount=type=sshmount一起使用。

使用 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 .

设置 ulimit (--ulimit)

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

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

笔记

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

笔记

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