構建變數

在 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.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 覆蓋 NODE_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

目標平臺引數持有使用 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 守護程式。

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

您使用 BUILDKIT_HOST 指定 BuildKit 守護程式的地址，以用作遠端構建器。這與將地址指定為 docker buildx create 的位置引數相同。

用法

$ export BUILDKIT_HOST=tcp://: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 設定為一個數字（預設為 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_FILE

為 docker buildx bake 指定一個或多個構建定義檔案。

此環境變數提供了 -f / --file 命令列標誌的替代方案。

可以透過系統路徑分隔符（Linux/macOS 上為“:”，Windows 上為“;”）來指定多個檔案

export BUILDX_BAKE_FILE=file1.hcl:file2.hcl

或者使用由 BUILDX_BAKE_FILE_SEPARATOR 變數定義的自定義分隔符

export BUILDX_BAKE_FILE_SEPARATOR=@
export BUILDX_BAKE_FILE=file1.hcl@file2.hcl

如果同時設定了 BUILDX_BAKE_FILE 和 -f 標誌，則僅使用透過 -f 提供的檔案。

如果列出的檔案不存在或無效，bake 將返回錯誤。

BUILDX_BAKE_FILE_SEPARATOR

控制 BUILDX_BAKE_FILE 環境變數中檔案路徑之間使用的分隔符。

如果您的檔案路徑包含預設分隔符字元，或者您想在不同平臺之間標準化分隔符，這會很有用。

export BUILDX_BAKE_PATH_SEPARATOR=@
export BUILDX_BAKE_FILE=file1.hcl@file2.hcl

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

允許您指定 SSH 代理套接字檔案路徑列表，以轉發到 Bake 以便在使用私有儲存庫中的遠端 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_METADATA_PROVENANCE

預設情況下，Buildx 透過--metadata-file 標誌在元資料檔案中包含最少的來源資訊。此環境變數允許您自定義元資料檔案中包含的來源資訊

• min 設定最小出處（預設）。
• max 設定完整出處。
• disabled、false 或 0 不設定任何來源。

BUILDX_METADATA_WARNINGS

預設情況下，Buildx 不透過--metadata-file 標誌在元資料檔案中包含構建警告。您可以將此環境變數設定為 1 或 true 以包含它們。

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