建置變數
在 Docker Build 中，建置引數 (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.20"
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 覆寫 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 常駐程式）的主機系統的操作系統、架構和平台變體。
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 .有關多平台建置引數的更多資訊，請參閱多平台引數
Proxy 引數
代理建置引數可讓您指定建置要使用的代理。您不需要在 Dockerfile 中宣告或參考這些引數。使用 --build-arg 指定代理就足以讓您的建置使用代理。
預設情況下，代理引數會自動從建置快取和 docker history 的輸出中排除。如果您在 Dockerfile 中參考這些引數，代理設定會儲存在建置快取中。
建置器會遵守下列代理建置引數。變數不區分大小寫。
HTTP_PROXYHTTPS_PROXYFTP_PROXYNO_PROXYALL_PROXY
要為您的建置設定代理
$ docker build --build-arg HTTP_PROXY=https://my-proxy.example.com .
有關代理建置引數的更多資訊，請參閱代理引數。
建置工具設定變數
下列環境變數可以啟用、停用或變更 Buildx 和 BuildKit 的行為。請注意，這些變數不用於設定建置容器；它們在建置內不可用，並且與 ENV 指令無關。它們用於設定 Buildx 用戶端或 BuildKit 常駐程式。
| 變數 | 類型 | 說明 |
|---|---|---|
| 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 | 字串 | 在指定位置產生 pprof CPU 效能分析。 |
| 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 內建的建置引數。
您可以用不同的方式表示環境變數的布林值。例如，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 預定義顏色