檢查您的建置設定

在 Buildx 0.15.0 版中導入

建置檢查是 Dockerfile 1.8 中導入的功能。它可讓您在執行建置之前驗證您的建置設定並執行一系列檢查。您可以將其視為 Dockerfile 和建置選項的進階 lint 形式，或是建置的預先執行模式。

您可以在建置檢查參考中找到可用的檢查清單，以及每個檢查的說明。

建置檢查的運作方式

通常，當您執行建置時，Docker 會按照指定執行 Dockerfile 和建置選項中的建置步驟。使用建置檢查時，Docker 不會執行建置步驟，而是會檢查您提供的 Dockerfile 和選項，並報告它偵測到的任何問題。

建置檢查適用於

在執行建置之前驗證您的 Dockerfile 和建置選項。
確保您的 Dockerfile 和建置選項與最新的最佳實務保持同步。
識別 Dockerfile 和建置選項中的潛在問題或反模式。

使用檢查進行建置

建置檢查支援於

Buildx 0.15.0 版和更新版本

docker/build-push-action

$ docker build .
[+] Building 3.5s (11/11) FINISHED
...

1 warning found (use --debug to expand):
  - Lint Rule 'JSONArgsRecommended': JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 7)

在此範例中，建置已成功執行，但回報了 JSONArgsRecommended 警告，因為 CMD 指令應該使用 JSON 陣列語法。

使用 GitHub Actions 時，檢查會顯示在提取請求的差異檢視中。

name: Build and push Docker images
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and push
        uses: docker/build-push-action@v6.6.0

更詳細的輸出

一般 docker build 的檢查警告會顯示簡潔訊息，其中包含規則名稱、訊息以及 Dockerfile 中問題發生的行號。如果您想查看有關檢查的更詳細資訊，可以使用 --debug 旗標。例如

$ docker --debug build .
[+] Building 3.5s (11/11) FINISHED
...

 1 warning found:
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 4)
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
More info: https://docker-docs.dev.org.tw/go/dockerfile/rule/json-args-recommended/
Dockerfile:4
--------------------
   2 |
   3 |     FROM alpine
   4 | >>> CMD echo "Hello, world!"
   5 |
--------------------

使用 --debug 旗標時，輸出會包含檢查文件的連結，以及 Dockerfile 中發現問題的程式碼片段。

在不建置的情況下檢查建置

若要執行建置檢查而不實際建置，您可以照常使用 docker build 指令，但要新增 --check 旗標。以下是一個範例

$ docker build --check .

此指令只會執行檢查並報告它發現的任何問題，而不是執行建置步驟。如果有任何問題，將會在輸出中報告。例如

使用 --check 的輸出

[+] Building 1.5s (5/5) FINISHED
=> [internal] connecting to local controller
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 253B
=> [internal] load metadata for docker.io/library/node:22
=> [auth] library/node:pull token for registry-1.docker.io
=> [internal] load .dockerignore
=> => transferring context: 50B
JSONArgsRecommended - https://docker-docs.dev.org.tw/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
Dockerfile:7
--------------------
5 |
6 |     COPY index.js .
7 | >>> CMD node index.js
8 |
--------------------

這個使用 --check 的輸出會顯示檢查的詳細訊息。

與一般建置不同，如果在使用 --check 旗標時報告任何違規，指令會以非零狀態碼結束。

檢查違規時建置失敗

預設情況下，建置的檢查違規會以警告形式報告，結束代碼為 0。您可以使用 Dockerfile 中的 check=error=true 指示，將 Docker 設定為在報告違規時建置失敗。這將導致在執行建置檢查後，在實際建置開始執行之前，建置就會出錯。

Dockerfile

1
2
3
4
5
# syntax=docker/dockerfile:1
# check=error=true

FROM alpine
CMD echo "Hello, world!"

如果沒有 # check=error=true 指示，此建置將以結束代碼 0 完成。但是，使用該指示時，建置檢查違規會導致非零結束代碼

$ docker build .
[+] Building 1.5s (5/5) FINISHED
...

 1 warning found (use --debug to expand):
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5)
Dockerfile:1
--------------------
   1 | >>> # syntax=docker/dockerfile:1
   2 |     # check=error=true
   3 |
--------------------
ERROR: lint violation found for rules: JSONArgsRecommended
$ echo $?
1

您也可以透過傳遞 BUILDKIT_DOCKERFILE_CHECK 建置引數，在 CLI 上設定錯誤指示

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" .

略過檢查

預設情況下，當您建置映像檔時，會執行所有檢查。如果您想略過特定檢查，可以在 Dockerfile 中使用 check=skip 指示。skip 參數會採用您想略過的檢查 ID 的 CSV 字串。例如

Dockerfile

# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing

FROM alpine AS BASE_STAGE
CMD echo "Hello, world!"

建置此 Dockerfile 不會導致任何檢查違規。

您也可以透過傳遞包含您想略過的檢查 ID 的 CSV 字串的 BUILDKIT_DOCKERFILE_CHECK 建置引數來略過檢查。例如

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" .

若要略過所有檢查，請使用 skip=all 參數

Dockerfile

# syntax=docker/dockerfile:1
# check=skip=all

針對檢查指示結合錯誤和略過參數

若要略過特定檢查並在檢查違規時出錯，請將以分號 (;) 分隔的 skip 和 error 參數傳遞至 Dockerfile 中的 check 指示或建置引數中。例如

Dockerfile

# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing;error=true

建置引數

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" .

實驗性檢查

在檢查升級為穩定之前，它們可能會以實驗性檢查的形式提供。預設情況下會停用實驗性檢查。若要查看可用的實驗性檢查清單，請參閱建置檢查參考。

若要啟用所有實驗性檢查，請將 BUILDKIT_DOCKERFILE_CHECK 建置引數設定為 experimental=all

$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .

您也可以使用 check 指示在 Dockerfile 中啟用實驗性檢查

Dockerfile

# syntax=docker/dockerfile:1
# check=experimental=all

若要選擇性地啟用實驗性檢查，您可以將您想啟用的檢查 ID 的 CSV 字串傳遞至 Dockerfile 中的 check 指示或作為建置引數。例如

Dockerfile

# syntax=docker/dockerfile:1
# check=experimental=JSONArgsRecommended,StageNameCasing

請注意，experimental 指令優先於 skip 指令，這表示無論您設定的 skip 指令為何，實驗性檢查都會執行。例如，如果您設定 skip=all 並啟用實驗性檢查，實驗性檢查仍然會執行。

Dockerfile

# syntax=docker/dockerfile:1
# check=skip=all;experimental=all

進一步閱讀

如需使用建置檢查的詳細資訊，請參閱