构建变量

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

警告

构建参数和环境变量不适合用于向构建传递秘密，因为它们会在最终镜像中暴露。相反，应使用秘密挂载或SSH挂载，这些方法可以安全地向构建暴露秘密。

更多信息请参见 构建秘密。

相似之处与不同之处

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

构建参数

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

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

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

有关如何使用构建参数的示例，请参见 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.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-arg CLI 标志：

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

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

• ARG Dockerfile 参考
• docker build --build-arg 参考

ENV 使用示例

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

# 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的值， 你可以结合环境变量和构建参数：

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

请注意，由于您设置的环境变量在容器中持续存在，使用它们可能会导致应用程序运行时产生意外的副作用。

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

• ENV 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}!"

在这个例子中，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。 评估是使用 Go 标准库中的 strconv.ParseBool 函数完成的。 详情请参阅 参考文档。

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为一个数字（默认为6）来更改TTY模式下活动步骤可见的日志行数。

$ 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_HEADER 密钥, 但在加载远程Bake文件时，便于在Bake中进行预认证。 支持的值为bearer（默认）和basic。

用法：

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

在使用私有Git仓库中的远程Bake定义时设置HTTP认证令牌。 这相当于 GIT_AUTH_TOKEN 密钥, 但在加载远程Bake文件时，便于在Bake中进行预认证。

用法：

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

BUILDX_BAKE_GIT_SSH

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

通常不需要设置此环境，因为Bake默认会使用SSH_AUTH_SOCK代理套接字。 只有在您想使用不同文件路径的套接字时，才需要指定此变量。 此变量可以使用逗号分隔的字符串来接受多个路径。

用法：

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

BUILDX_BUILDER

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

用法：

$ export BUILDX_BUILDER=my-builder

BUILDX_CONFIG

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

• $BUILDX_CONFIG
• $DOCKER_CONFIG/buildx
• ~/.docker/buildx (默认)

用法：

$ export BUILDX_CONFIG=/usr/local/etc

BUILDX_CPU_PROFILE

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

注意

此属性仅在开发Buildx时有用。性能分析数据不适用于分析构建的性能。

用法：

$ export BUILDX_CPU_PROFILE=buildx_cpu.prof

BUILDX_EXPERIMENTAL

启用实验性构建功能。

用法：

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

如果指定，Buildx 将在指定位置生成一个 pprof 内存配置文件。

注意

此属性仅在开发Buildx时有用。性能分析数据不适用于分析构建的性能。

用法：

$ export BUILDX_MEM_PROFILE=buildx_mem.prof

BUILDX_NO_DEFAULT_ATTESTATIONS

默认情况下，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