构建变量

目录

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

警告

构建参数和环境变量不适合用于向构建传递 Secrets，因为它们会暴露在最终镜像中。相反，请使用 Secret Mounts 或 SSH Mounts，它们可以安全地将 Secrets 暴露给你的构建。

有关更多信息，请参阅构建 Secrets。

异同点

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

构建参数

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

构建参数除非在指令中使用，否则对构建没有影响。除非从 Dockerfile 显式传递到镜像文件系统或配置中，否则它们在从镜像实例化的容器中无法访问或不存在。它们可能会保留在镜像元数据中、作为来源 Attestations 以及在镜像历史记录中，这就是它们不适合用于存储 Secrets 的原因。

它们使 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.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 .

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

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 覆盖 NODE_ENV 的默认值

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

请注意，由于你设置的环境变量会保留在容器中，使用它们可能会导致应用程序运行时出现意外的副作用。

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

作用域

在 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 Daemon）的主机系统的操作系统、架构和平台变体。

  • BUILDPLATFORM
  • BUILDOS
  • BUILDARCH
  • BUILDVARIANT

目标平台参数保存了构建的目标平台的值，这些值使用 docker build 命令的 --platform 标志指定。

  • 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 Daemon。

变量类型描述
BUILDKIT_COLORS字符串配置终端输出的文本颜色。
BUILDKIT_HOST字符串指定用于远程 Builder 的主机。
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字符串指定要使用的 Builder 实例。
BUILDX_CONFIG字符串指定配置、状态和日志的位置。
BUILDX_CPU_PROFILE字符串在指定位置生成 pprof CPU 性能分析。
BUILDX_EXPERIMENTAL布尔值开启实验性功能。
BUILDX_GIT_CHECK_DIRTY布尔值启用脏 Git Checkout 检测。
BUILDX_GIT_INFO布尔值在来源 Attestations 中移除 Git 信息。
BUILDX_GIT_LABELS字符串 | 布尔值向镜像添加 Git 来源标签。
BUILDX_MEM_PROFILE字符串在指定位置生成 pprof 内存性能分析。
BUILDX_METADATA_PROVENANCE字符串 | 布尔值自定义包含在元数据文件中的来源信息。
BUILDX_METADATA_WARNINGS字符串在元数据文件中包含构建警告。
BUILDX_NO_DEFAULT_ATTESTATIONS布尔值关闭默认的来源 Attestations。
BUILDX_NO_DEFAULT_LOAD布尔值默认情况下关闭加载镜像到镜像存储。
EXPERIMENTAL_BUILDKIT_SOURCE_POLICY字符串指定 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 设置为任何值都会关闭彩色输出，正如 no-color.org 所建议的那样。

BUILDKIT_HOST

要求： Docker Buildx 0.9.0 及更高版本

您可以使用 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
  • quiet
  • 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 source policy 文件，用于使用固定依赖项创建可重现构建。

$ 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

需要： Docker Buildx 0.14.0 及更高版本

使用私有 Git 仓库中的远程 Bake 定义时，设置 HTTP 身份验证方案。这等同于 GIT_AUTH_HEADER secret，但有助于在加载远程 Bake 文件时，在 Bake 中进行预检身份验证。支持的值有 bearer（默认）和 basic。

用法

$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic

BUILDX_BAKE_GIT_AUTH_TOKEN

需要： Docker 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

需要： Docker Buildx 0.14.0 及更高版本

允许您指定 SSH 代理套接字文件路径列表，以转发到 Bake，以便在使用私有仓库中的远程 Bake 定义时对 Git 服务器进行身份验证。这类似于构建的 SSH mounts，但有助于在解析构建定义时，在 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

需要： Docker Buildx 0.18.0 及更高版本

如果指定，Buildx 会在指定位置生成 pprof CPU profile。

注意

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

用法

$ export BUILDX_CPU_PROFILE=buildx_cpu.prof

BUILDX_EXPERIMENTAL

启用实验性构建功能。

用法

$ export BUILDX_EXPERIMENTAL=1

BUILDX_GIT_CHECK_DIRTY

需要： Docker Buildx 0.10.4 及更高版本

设置为 true 时，检查 provenance attestations 的源代码控制信息中是否存在 dirty 状态。

用法

$ export BUILDX_GIT_CHECK_DIRTY=1

BUILDX_GIT_INFO

需要： Docker Buildx 0.10.0 及更高版本

设置为 false 时，从 provenance attestations 中删除源代码控制信息。

用法

$ export BUILDX_GIT_INFO=0

BUILDX_GIT_LABELS

需要： Docker Buildx 0.10.0 及更高版本

根据 Git 信息，为构建的镜像添加 provenance 标签。这些标签是

  • 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 以包含所有标签。

如果仓库处于 dirty 状态，revision 将带有 -dirty 后缀。

BUILDX_MEM_PROFILE

需要： Docker Buildx 0.18.0 及更高版本

如果指定，Buildx 会在指定位置生成 pprof memory profile。

注意

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

用法

$ export BUILDX_MEM_PROFILE=buildx_mem.prof

BUILDX_METADATA_PROVENANCE

需要： Docker Buildx 0.14.0 及更高版本

默认情况下，Buildx 通过 --metadata-file 标志在 metadata 文件中包含最少的 provenance 信息。此环境变量允许您自定义 metadata 文件中包含的 provenance 信息

  • min 设置最少的 provenance（默认）。
  • max 设置完整的 provenance。
  • disabled、false 或 0 不设置任何 provenance。

BUILDX_METADATA_WARNINGS

需要： Docker Buildx 0.16.0 及更高版本

默认情况下，Buildx 不通过 --metadata-file 标志在 metadata 文件中包含构建警告。您可以将此环境变量设置为 1 或 true 来包含它们。

BUILDX_NO_DEFAULT_ATTESTATIONS

需要： Docker Buildx 0.10.4 及更高版本

默认情况下，BuildKit v0.11 及更高版本会为构建的镜像添加 provenance attestations。设置 BUILDX_NO_DEFAULT_ATTESTATIONS=1 以禁用默认的 provenance attestations。

用法

$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1

BUILDX_NO_DEFAULT_LOAD

使用 docker 驱动构建镜像时，构建完成后镜像会自动加载到镜像存储中。设置 BUILDX_NO_DEFAULT_LOAD 以禁用将镜像自动加载到本地容器存储的行为。

用法

$ export BUILDX_NO_DEFAULT_LOAD=1
页面选项