构建变量

在 Docker Build 中，构建参数（）和环境变量（）两者都是将信息传递到构建过程中的一种方式。您可以使用它们来参数化构建，从而实现更灵活和可配置的构建。ARGENV

警告
生成参数和环境变量不适合传递机密添加到您的构建中，因为它们会在最终镜像中公开。相反，请使用 secret 挂载或 SSH 挂载，它们安全地向构建公开 secret。
有关更多信息，请参阅构建密钥。

相似之处和不同之处

生成参数和环境变量类似。它们都在 Dockerfile 中声明，并且可以使用命令的标志进行设置。两者都可用于参数化构建。但它们都有不同的目的。docker build

构建参数

构建参数是 Dockerfile 本身的变量。使用它们来参数化 Dockerfile 指令的值。例如，您可以使用 build 参数指定要安装的依赖项的版本。

除非在指令中使用 build 参数，否则 build 参数对 build 没有影响。它们不可访问，也无法存在于从镜像实例化的容器中除非从 Dockerfile 显式传递到镜像文件系统或配置中。它们可能会作为出处证明和镜像历史记录中保留。这就是为什么他们不适合持有秘密。

它们使 Dockerfile 更灵活，更易于维护。

有关如何使用 build 参数的示例，请参阅 ARG 使用示例。

环境变量

环境变量传递到构建执行环境，并保留在从镜像实例化的容器中。

环境变量主要用于：

配置构建的执行环境
为容器设置默认环境变量

环境变量（如果已设置）可以直接影响构建的执行。以及应用程序的行为或配置。

您不能在构建时覆盖或设置环境变量。环境变量的值必须在 Dockerfile 中声明。您可以组合环境变量和构建参数以允许环境变量。

有关如何使用环境变量配置构建的示例，请参阅 ENV 使用示例。

`ARG` 使用示例

构建参数通常用于指定组件的版本，例如，在构建中使用的镜像变体或包版本。

将版本指定为生成参数允许使用不同的版本进行生成而无需手动更新 Dockerfile。它还使维护 Dockerfile 变得更加容易，因为它允许您在文件顶部声明版本。

Build Arguments 也可以是一种在多个位置重用值的方法。例如，如果您在构建中使用了多种风格的，您可以确保您使用的是相同版本的 Everywhere：alpinealpine

golang:1.22-alpine${ALPINE_VERSION}
python:3.12-alpine${ALPINE_VERSION}
nginx:1-alpine${ALPINE_VERSION}

以下示例定义 build 参数的版本并使用 build 参数。nodealpine

# syntax=docker/dockerfile:1

ARG NODE_VERSION="20"
ARG ALPINE_VERSION="3.21"

FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base
WORKDIR /src

FROM base AS build
COPY package*.json ./
RUN npm ci
RUN npm run build

FROM base AS production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /src/dist/ .
CMD ["node", "app.js"]

在这种情况下，build 参数具有默认值。在调用生成时指定其值是可选的。要覆盖默认值，您可以使用 CLI 标志：--build-arg

$ docker build --build-arg NODE_VERSION=current .

有关如何使用 build 参数的更多信息，请参阅：

`ENV` 使用示例

声明环境变量会使变量可用于构建阶段中的所有后续说明。以下示例显示了在使用安装 JavaScript 依赖项之前的示例设置。设置该变量会省略仅本地开发所需的包。ENVNODE_ENVproductionnpmnpm

# syntax=docker/dockerfile:1

FROM node:20
WORKDIR /app
COPY package*.json ./
ENV NODE_ENV=production
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]

默认情况下，环境变量在构建时不进行配置。如果要在构建时更改 an 的值，您可以组合环境变量和构建参数：ENV

# syntax=docker/dockerfile:1

FROM node:20
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV
WORKDIR /app
COPY package*.json ./
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]

使用此 Dockerfile，您可以使用来覆盖默认值：--build-argENV

$ docker build --build-arg NODE_ENV=development .

请注意，由于您设置的环境变量保留在容器中，因此使用它们可能会对应用程序的运行时产生意外的副作用。

有关如何在构建中使用环境变量的更多信息，请参阅：

环境Dockerfile 参考

范围

在 Dockerfile 的全局范围内声明的构建参数不会自动继承到构建阶段。它们只能在全局范围内访问。

# syntax=docker/dockerfile:1

# The following build argument is declared in the global scope:
ARG NAME="joe"

FROM alpine
# The following instruction doesn't have access to the $NAME build argument
# because the argument was defined in the global scope, not for this stage.
RUN echo "hello ${NAME}!"

此示例中的命令计算结果为，因为 build 参数的值超出范围。要将全局构建参数继承到阶段中，您必须使用它们：echohello !NAME

# syntax=docker/dockerfile:1

# Declare the build argument in the global scope
ARG NAME="joe"

FROM alpine
# Consume the build argument in the build stage
ARG NAME
RUN echo $NAME

在 stage 中声明或使用 build 参数后，它由子阶段自动继承。

# syntax=docker/dockerfile:1
FROM alpine AS base
# Declare the build argument in the build stage
ARG NAME="joe"

# Create a new stage based on "base"
FROM base AS build
# The NAME build argument is available here
# since it's declared in a parent stage
RUN echo "hello $NAME!"

下图进一步举例说明了 build 参数和 environment variable inheritance 适用于多阶段构建。

预定义的构建参数

本节介绍默认情况下可用于所有构建的预定义构建参数。

多平台 build 参数

多平台生成参数描述生成的生成和目标平台。

构建平台是操作系统、架构和平台变体运行构建器（BuildKit 守护程序）的主机系统。

BUILDPLATFORM
BUILDOS
BUILDARCH
BUILDVARIANT

目标平台参数与构建的目标平台具有相同的值。使用命令的标志指定。--platformdocker build

TARGETPLATFORM
TARGETOS
TARGETARCH
TARGETVARIANT

这些参数对于在多平台构建中进行交叉编译非常有用。它们在 Dockerfile 的全局范围内可用，但它们不会自动被 Build 阶段继承。要在 stage 中使用它们，您必须声明它们：

# syntax=docker/dockerfile:1

# Pre-defined build arguments are available in the global scope
FROM --platform=$BUILDPLATFORM golang
# To inherit them to a stage, declare them with ARG
ARG TARGETOS
RUN GOOS=$TARGETOS go build -o ./exe .

有关多平台构建参数的更多信息，请参阅多平台参数

代理参数

代理生成参数允许您指定要用于生成的代理。您无需在 Dockerfile 中声明或引用这些参数。指定代理就足以使您的构建使用该代理。--build-arg

代理参数会自动从构建缓存中排除和 default 的输出。如果您引用了 Dockerfile 中的参数，则代理配置最终位于 Build Cache 中。docker history

构建器遵循以下代理构建参数。这些变量不区分大小写。

HTTP_PROXY
HTTPS_PROXY
FTP_PROXY
NO_PROXY
ALL_PROXY

要为您的构建配置代理，请执行以下操作：

$ docker build --build-arg HTTP_PROXY=https://my-proxy.example.com .

有关代理构建参数的更多信息，请参阅代理参数。

构建工具配置变量

以下环境变量启用、禁用或更改 Buildx 和 BuildKit 的行为。请注意，这些变量不用于配置构建容器; 它们在 build 中不可用，并且与指令无关。它们用于配置 Buildx 客户端或 BuildKit 守护进程。ENV

变量	类型	描述
BUILDKIT_COLORS	字符串	配置终端输出的文本颜色。
BUILDKIT_HOST	字符串	指定要用于远程构建器的主机。
BUILDKIT_PROGRESS	字符串	配置进度输出的类型。
BUILDKIT_TTY_LOG_LINES	字符串	日志行数（对于 TTY 模式下的活动步骤）。
BUILDX_BAKE_GIT_AUTH_HEADER	字符串	远程 Bake 文件的 HTTP 身份验证方案。
BUILDX_BAKE_GIT_AUTH_TOKEN	字符串	远程 Bake 文件的 HTTP 身份验证令牌。
BUILDX_BAKE_GIT_SSH	字符串	远程 Bake 文件的 SSH 身份验证。
BUILDX_BUILDER	字符串	指定要使用的生成器实例。
BUILDX_CONFIG	字符串	指定配置、状态和日志的位置。
BUILDX_CPU_PROFILE	字符串	在指定位置生成 CPU 配置文件。`pprof`
BUILDX_EXPERIMENTAL	布尔	开启实验性功能。
BUILDX_GIT_CHECK_DIRTY	布尔	启用脏 Git 签出检测。
BUILDX_GIT_INFO	布尔	删除来源证明中的 Git 信息。
BUILDX_GIT_LABELS	字符串 \|布尔	向镜像添加 Git 出处标签。
BUILDX_MEM_PROFILE	字符串	在指定位置生成内存配置文件。`pprof`
BUILDX_NO_DEFAULT_ATTESTATIONS	布尔	关闭默认出处证明。
BUILDX_NO_DEFAULT_LOAD	布尔	默认情况下，关闭将镜像加载到镜像存储。
EXPERIMENTAL_BUILDKIT_SOURCE_POLICY	字符串	指定 BuildKit 源策略文件。

BuildKit 还支持一些额外的配置参数。参考 BuildKit 内置的 build args。

您可以用不同的方式表示环境变量的布尔值。例如，，和 all 的计算结果为 true。使用 Go 标准库中的函数进行评估。有关详细信息，请参阅参考文档。true1Tstrconv.ParseBool

BUILDKIT_COLORS

更改终端输出的颜色。设置为 CSV 字符串格式如下：BUILDKIT_COLORS

$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white"

颜色值可以是任何有效的 RGB 十六进制代码，也可以是 BuildKit 预定义的颜色之一。

设置为 any 将关闭彩色输出，如 no-color.org 所建议的那样。NO_COLOR

BUILDKIT_HOST

您可以使用来指定要使用的 BuildKit 守护进程的地址作为远程构建器。这与将地址指定为位置参数设置为 .BUILDKIT_HOSTdocker buildx create

用法：

$ export BUILDKIT_HOST=tcp://localhost:1234
$ docker buildx create --name=remote --driver=remote

如果同时指定环境变量和位置 argument，则参数优先。BUILDKIT_HOST

BUILDKIT_PROGRESS

设置 BuildKit 进度输出的类型。有效值为：

auto（默认）
plain
tty
rawjson

用法：

$ export BUILDKIT_PROGRESS=plain

BUILDKIT_TTY_LOG_LINES

您可以通过以下方式更改 TTY 模式下活动步骤可见的日志行数设置为一个数字（默认为）。BUILDKIT_TTY_LOG_LINES6

$ export BUILDKIT_TTY_LOG_LINES=8

EXPERIMENTAL_BUILDKIT_SOURCE_POLICY

允许您指定 BuildKit 源策略文件，用于创建具有固定依赖项的可重现构建。

$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json

例：

{
  "rules": [
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "docker-image://docker.io/library/alpine:latest"
      },
      "updates": {
        "identifier": "docker-image://docker.io/library/alpine:latest@sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454"
      }
    },
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md"
      },
      "updates": {
        "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"}
      }
    },
    {
      "action": "DENY",
      "selector": {
        "identifier": "docker-image://docker.io/library/golang*"
      }
    }
  ]
}

BUILDX_BAKE_GIT_AUTH_HEADER

在 Buildx 版本中引入 0.14.0

在私有 Git 存储库中使用远程 Bake 定义时设置 HTTP 身份验证方案。这相当于 GIT_AUTH_HEADER secret，但有助于在加载远程 Bake 文件时在 Bake 中进行印前身份验证。支持的值为（default）和。bearerbasic

用法：

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

在 Buildx 版本中引入 0.14.0

在私有 Git 存储库中使用远程 Bake 定义时设置 HTTP 身份验证令牌。这相当于 GIT_AUTH_TOKEN secret，但有助于在加载远程 Bake 文件时在 Bake 中进行印前身份验证。

用法：

$ export BUILDX_BAKE_GIT_AUTH_TOKEN=$(cat git-token.txt)

BUILDX_BAKE_GIT_SSH

在 Buildx 版本中引入 0.14.0

允许您指定要转发到 Bake 的 SSH 代理套接字文件路径列表用于在私有存储库中使用远程 Bake 定义时向 Git 服务器进行身份验证。这类似于构建的 SSH 挂载，但有助于在解析构建定义时在 Bake 中进行飞行前身份验证。

通常不需要设置此环境，因为 Bake 将默认使用代理套接字。如果要使用具有不同文件路径的套接字，则只需指定此变量。此变量可以使用逗号分隔的字符串采用多个路径。SSH_AUTH_SOCK

用法：

$ export BUILDX_BAKE_GIT_SSH=/run/foo/listener.sock,~/.creds/ssh.sock

BUILDX_BUILDER

覆盖配置的生成器实例。与 CLI 标志相同。docker buildx --builder

用法：

$ export BUILDX_BUILDER=my-builder

BUILDX_CONFIG

可用于指定要用于生成的目录 configuration、state 和 logs。此目录的查找顺序为遵循：BUILDX_CONFIG

$BUILDX_CONFIG
$DOCKER_CONFIG/buildx
~/.docker/buildx（默认）

用法：

$ export BUILDX_CONFIG=/usr/local/etc

BUILDX_CPU_PROFILE

在 Buildx 版本中引入 0.18.0

如果指定，Buildx 将在指定位置生成 CPU 配置文件。pprof

注意
此属性仅在开发 Buildx 时有用。分析数据与分析构建的性能无关。

用法：

$ export BUILDX_CPU_PROFILE=buildx_cpu.prof

BUILDX_EXPERIMENTAL

启用实验性构建功能。

用法：

$ export BUILDX_EXPERIMENTAL=1

BUILDX_GIT_CHECK_DIRTY

在 Buildx 版本 0.10.4 中引入

当设置为 true 时，检查来源证明的源代码控制信息中的 dirty 状态。

用法：

$ export BUILDX_GIT_CHECK_DIRTY=1

BUILDX_GIT_INFO

在 Buildx 版本 0.10.0 中引入

设置为 false 时，从来源证明中删除源代码控制信息。

用法：

$ export BUILDX_GIT_INFO=0

BUILDX_GIT_LABELS

在 Buildx 版本 0.10.0 中引入

根据 Git 信息将来源标签添加到您构建的镜像中。这标签是：

com.docker.image.source.entrypoint：Dockerfile 相对于的位置项目根目录
org.opencontainers.image.revision：Git 提交修订版
org.opencontainers.image.source：仓库的 SSH 或 HTTPS 地址

例：

  "Labels": {
    "com.docker.image.source.entrypoint": "Dockerfile",
    "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b",
    "org.opencontainers.image.source": "git@github.com:foo/bar.git"
  }

用法：

设置为包括和标签。BUILDX_GIT_LABELS=1entrypointrevision
设置为包括所有标签。BUILDX_GIT_LABELS=full

如果存储库处于脏状态，则将获得后缀。revision-dirty

BUILDX_MEM_PROFILE

在 Buildx 版本中引入 0.18.0

如果指定，则 Buildx 会在指定的位置。pprof

注意
此属性仅在开发 Buildx 时有用。分析数据与分析构建的性能无关。

用法：

$ export BUILDX_MEM_PROFILE=buildx_mem.prof

BUILDX_NO_DEFAULT_ATTESTATIONS

在 Buildx 版本 0.10.4 中引入

默认情况下，BuildKit v0.11 及更高版本会为您建。设置为禁用默认来源证明。BUILDX_NO_DEFAULT_ATTESTATIONS=1

用法：

$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1

BUILDX_NO_DEFAULT_LOAD

当您使用驱动程序构建镜像时，镜像会自动在构建完成后加载到镜像存储中。设置为禁用将镜像自动加载到本地容器存储。dockerBUILDX_NO_DEFAULT_LOAD

用法：

$ export BUILDX_NO_DEFAULT_LOAD=1