构建变量

在 Docker Build 中，构建参数 ( ARG) 和环境变量 ( ENV) 都用作将信息传递到构建过程的方法。您可以使用它们来参数化构建，从而实现更灵活和可配置的构建。

警告

构建参数和环境变量不适合将机密传递给构建，因为它们在最终映像中公开。相反，请使用秘密安装或 SSH 安装，这可以安全地向您的构建公开秘密。

有关详细信息，请参阅 构建机密。

共同点和不同点

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

构建论点

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

除非在指令中使用，否则构建参数对构建没有影响。它们无法访问或存在于从映像实例化的容器中，除非明确从 Dockerfile 传递到映像文件系统或配置中。它们可能会保留在图像元数据中，作为出处证明和图像历史记录，这就是它们不适合保守秘密的原因。

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

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

环境变量

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

环境变量主要用于：

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

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

您无法在构建时覆盖或设置环境变量。环境变量的值必须在 Dockerfile 中声明。您可以将环境变量和构建参数结合起来，以允许在构建时配置环境变量。

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

ARG 使用示例

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

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

构建参数也可以是在多个地方重用值的一种方法。例如，如果您在构建中使用多种风格的，则可以确保在各处alpine使用相同版本的：alpine

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

以下示例定义了构建参数的版本node和使用方式。alpine

# syntax=docker/dockerfile:1

ARG NODE_VERSION="20"
ARG ALPINE_VERSION="3.19"

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-argCLI 标志：

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

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

• ARGDockerfile 参考
• docker build --build-arg参考

ENV 使用示例

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

# 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"]

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

# 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-arg覆盖默认值ENV：

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

请注意，由于您设置的环境变量保留在容器中，因此使用它们可能会给应用程序的运行时带来意想不到的副作用。

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

• ENVDockerfile 参考

范围界定

在 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}!"

echo此示例中的命令的计算结果为 ，因为构建参数hello ! 的值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

一旦在阶段中声明或使用构建参数，它就会自动被子阶段继承。

# 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!"

下图进一步举例说明了构建参数和环境变量继承如何用于多阶段构建。

预定义的构建参数

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

多平台构建参数

多平台构建参数描述了构建的构建和目标平台。

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

• BUILDPLATFORM
• BUILDOS
• BUILDARCH
• BUILDVARIANT

目标平台参数与构建的目标平台保持相同的值，使用命令--platform的标志指定docker build。

• TARGETPLATFORM
• TARGETOS
• TARGETARCH
• TARGETVARIANT

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

# 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足以使您的构建使用该代理。

默认情况下，代理参数会自动从构建缓存和输出中排除docker history。如果您确实引用了 Dockerfile 中的参数，则代理配置最终会出现在构建缓存中。

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

• HTTP_PROXY
• HTTPS_PROXY
• FTP_PROXY
• NO_PROXY
• ALL_PROXY

要为您的构建配置代理：

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

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

构建工具配置变量

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

BuildKit 还支持一些额外的配置参数。请参阅 BuildKit 内置构建参数。

您可以用不同的方式表达环境变量的布尔值。例如，true、1和T全部评估为 true。评估是使用strconv.ParseBoolGo标准库中的函数完成的。有关详细信息，请参阅 参考文档。

BUILDKIT_COLORS

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

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

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

按照no-color.org的建议，设置NO_COLOR为任何值都会关闭彩色输出 。

BUILDKIT_HOST

您可以使用BUILDKIT_HOST指定用作远程构建器的 BuildKit 守护程序的地址。这与将地址指定为 的位置参数相同docker buildx create。

用法：

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

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

BUILDKIT_PROGRESS

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

• auto（默认）
• plain
• tty
• rawjson

用法：

$ export BUILDKIT_PROGRESS=plain

BUILDKIT_TTY_LOG_LINES

BUILDKIT_TTY_LOG_LINES您可以通过设置为数字（默认为）来更改 tty 模式下活动步骤可见的日志行数6。

$ 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

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

用法：

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

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

用法：

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

BUILDX_BAKE_GIT_SSH

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

通常不需要设置此环境，因为 BakeSSH_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

构建DX_配置

您可以用来BUILDX_CONFIG指定用于构建配置、状态和日志的目录。该目录的查找顺序如下：

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

用法：

$ export BUILDX_CONFIG=/usr/local/etc

BUILDX_实验

启用实验性构建功能。

用法：

$ export BUILDX_EXPERIMENTAL=1

BUILDX_GIT_CHECK_DIRTY

设置为 true 时，检查源控制信息中的脏状态以获取 出处证明。

用法：

$ export BUILDX_GIT_CHECK_DIRTY=1

BUILDX_GIT_INFO

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

用法：

$ export BUILDX_GIT_INFO=0

BUILDX_GIT_LABELS

根据 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=1为包括entrypoint和revision标签。
• 设置BUILDX_GIT_LABELS=full为包括所有标签。

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

BUILDX_NO_DEFAULT_ATESTATIONS

默认情况下，BuildKit v0.11 及更高版本会 向您构建的映像添加出处证明。设置BUILDX_NO_DEFAULT_ATTESTATIONS=1为禁用默认来源证明。

用法：

$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1

BUILDX_NO_DEFAULT_LOAD

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

用法：

$ export BUILDX_NO_DEFAULT_LOAD=1