docker buildx build
| 說明 | 開始建置 |
|---|---|
| 用法 | docker buildx build [選項] 路徑 | URL | - |
| 別名 | docker build docker builder build docker image build docker buildx b |
說明
docker buildx build 指令使用 BuildKit 開始建置。
選項
| 選項 | 預設值 | 說明 |
|---|---|---|
--add-host | 新增自訂主機到 IP 的映射（格式：host:ip） | |
--allow | 允許額外的權限（例如，network.host、`security.insecure`） | |
--annotation | 新增註釋到映像檔 | |
--attest | 證明參數（格式：type=sbom,generator=image） | |
--build-arg | 設定建置時期變數 | |
--build-context | 額外的建置上下文（例如，name=path） | |
--cache-from | 外部快取來源（例如，user/app:cache、type=local,src=path/to/dir） | |
--cache-to | 快取匯出目的地（例如，user/app:cache、type=local,dest=path/to/dir） | |
--call | build | 設定評估建置的方法（`check`、`outline`、`targets`） |
--cgroup-parent | 設定建置期間 `RUN` 指令的父 cgroup | |
--check | --call=check 的簡寫 | |
--detach | 實驗性 (CLI) detach buildx server (僅支援 Linux) | |
-f, --file | Dockerfile 的名稱（預設值：PATH/Dockerfile） | |
--iidfile | 將映像檔 ID 寫入檔案 | |
--label | 設定影像的後設資料 | |
--load | --output=type=docker 的簡寫 | |
--metadata-file | 將建置結果後設資料寫入檔案 | |
--network | 設定建置期間 RUN 指令的網路模式 | |
--no-cache | 建置影像時不使用快取 | |
--no-cache-filter | 不快取指定的階段 | |
-o, --output | 輸出目的地（格式：type=local,dest=path） | |
--platform | 設定建置的目標平台 | |
--progress | auto | 設定進度輸出的類型（auto、plain、tty、rawjson）。使用 plain 來顯示容器輸出 |
--provenance | --attest=type=provenance 的簡寫 | |
--pull | 永遠嘗試提取所有參考的影像 | |
--push | --output=type=registry 的簡寫 | |
-q, --quiet | 隱藏建置輸出，成功時印出影像 ID | |
--root | 實驗性 (CLI) 指定要連線的伺服器根目錄 | |
--sbom | --attest=type=sbom 的簡寫 | |
--secret | 要公開給建置的秘密資訊（格式：id=mysecret[,src=/local/secret]） | |
--server-config | 實驗性 (CLI) 指定 buildx 伺服器設定檔（僅在啟動新伺服器時使用） | |
--shm-size | 建置容器的共享記憶體大小 | |
--ssh | 要公開給建置的 SSH 代理程式通訊端或金鑰（格式：default|<id>[=<socket>|<key>[,<key>]]） | |
-t, --tag | 名稱和選用的標籤（格式：name:tag） | |
--target | 設定要建置的目標建置階段 | |
--ulimit | Ulimit 選項 |
範例
將項目新增至容器 hosts 檔案 (--add-host)
您可以使用一個或多個 --add-host 旗標，將其他主機新增至建置容器的 /etc/hosts 檔案中。此範例為名為 my-hostname 和 my_hostname_v6 的主機新增靜態位址
$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
如果您需要建置連線到主機上執行的服務，您可以將特殊的 host-gateway 值用於 --add-host。在以下範例中，建置容器會將 host.docker.internal 解析為主機的閘道器 IP。
$ docker buildx build --add-host host.docker.internal=host-gateway .
您可以將 IPv6 位址括在方括弧中。= 和 : 都是有效的區隔符號。以下範例中的兩種格式都是有效的
$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
建立註釋 (--annotation)
--annotation="key=value"
--annotation="[type:]key=value"將 OCI 註釋新增至影像索引、資訊清單或描述元。以下範例將 foo=bar 註釋新增至影像資訊清單
$ docker buildx build -t TAG --annotation "foo=bar" --push .
您可以選擇性地新增類型前綴來指定註釋的層級。預設情況下，會註釋影像資訊清單。以下範例將 foo=bar 註釋新增至影像索引，而不是資訊清單
$ docker buildx build -t TAG --annotation "index:foo=bar" --push .
您可以指定多種類型，以逗號 (,) 分隔，以將註釋新增至多個影像元件。以下範例將 foo=bar 註釋新增至影像索引、描述元、資訊清單
$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .
您也可以在類型前綴中指定平台限定詞，以方括弧 ([os/arch]) 括起來，以將註釋套用至具有相符平台的資訊清單子集。以下範例僅將 foo=bar 註釋新增至具有 linux/amd64 平台的資訊清單
$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .
平台限定詞不支援萬用字元；您無法指定像 manifest[linux/*] 這樣的類型前綴，以僅將註釋新增至以 linux 作為作業系統平台的資訊清單。
如需註釋的詳細資訊，請參閱註釋。
建立證明 (--attest)
--attest=type=sbom,...
--attest=type=provenance,...建立影像證明。BuildKit 目前支援
sbom- 軟體物料清單。使用
--attest=type=sbom在建置時為影像產生 SBOM。或者，您可以使用--sbom簡寫。如需詳細資訊，請參閱這裡。
provenance- SLSA 出處使用
--attest=type=provenance在建置時為影像產生出處。或者，您可以使用--provenance簡寫。預設情況下，會為建置結果建立最少的出處證明，這只會附加到推送到登錄處的影像。
如需詳細資訊，請參閱這裡。
允許額外的權限授權 (--allow)
--allow=ENTITLEMENT允許額外的權限授權。授權清單
network.host- 允許使用主機網路執行。security.insecure- 允許在沒有沙盒的情況下執行。請參閱相關的 Dockerfile 擴充功能。
要啟用授權，BuildKit 精靈也需要使用 --allow-insecure-entitlement 來允許它們（請參閱create --buildkitd-flags）。
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
設定建置時變數 (--build-arg)
您可以在 Dockerfile 中使用 ENV 指令來定義變數值。這些值會保留在建置的影像中。通常，持續性不是您想要的。使用者希望根據建置影像的主機來指定不同的變數。
一個很好的例子是 http_proxy 或用於提取中間檔案的來源版本。ARG 指令允許 Dockerfile 作者定義使用者可以在建置時使用 --build-arg 旗標設定的值
$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .
此旗標允許您傳遞建置時變數，這些變數在 Dockerfile 的 RUN 指令中可以像一般環境變數一樣被存取。這些值不像 ENV 值那樣保留在中間或最終影像中。您必須為每個建置參數新增 --build-arg。
使用此旗標不會改變您在建置程序回應 Dockerfile 中的 ARG 行時看到的輸出。
有關使用 ARG 和 ENV 指令的詳細資訊，請參閱Dockerfile 參考。
您也可以在沒有值的情況下使用 --build-arg 旗標，在這種情況下，精靈會將本地環境中的值傳播到它正在建置的 Docker 容器中
$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker buildx build --build-arg HTTP_PROXY .
此範例類似於 docker run -e 的運作方式。請參閱docker run 文件以取得更多資訊。
還有一些有用的內建建置參數，例如
BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>：觸發 git context 保留.git目錄BUILDKIT_INLINE_CACHE=<bool>：是否將快取後設資料內嵌到影像設定中BUILDKIT_MULTI_PLATFORM=<bool>：選擇加入確定性輸出，無論是否為多平台輸出
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .
在Dockerfile 參考文件中進一步了解內建建置參數。
額外的建置上下文 (--build-context)
--build-context=name=VALUE使用指定的內容定義額外的建置上下文。在 Dockerfile 中，當使用 FROM name 或 --from=name 時，可以存取上下文。當 Dockerfile 定義具有相同名稱的階段時，它會被覆蓋。
值可以是本地來源目錄、符合本地 OCI 佈局的目錄、容器映像（使用 docker-image:// 前綴）、Git 或 HTTP URL。
將 alpine:latest 替換為固定版本。
$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
公開次要的本地來源目錄。
$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /使用 OCI 佈局目錄作為建置上下文。
從本地的 符合 OCI 佈局的目錄 來源映像，可以使用標籤或摘要。
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /
FROM fooOCI 佈局目錄必須符合 OCI 佈局規範。您可以使用標籤或確切的摘要來參考佈局中的映像。
覆寫已設定的建置器執行個體 (--builder)。
與 buildx --builder 相同。
使用外部快取來源進行建置 (--cache-from)。
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]使用外部快取來源進行建置。支援的類型有 registry、local、gha 和 s3。