檢查您的組建設定

目錄
可用性： 測試版 (Beta)
需求： Docker Buildx 0.15.0 或更高版本

組建檢查是 Dockerfile 1.8 中引入的一項功能。它允許您在執行組建之前驗證組建設定並進行一系列檢查。可以將其視為 Dockerfile 和組建選項的進階 lint 工具，或者是組建的試運行（dry-run）模式。

您可以在組建檢查參考中找到可用檢查的清單及其說明。

組建檢查如何運作

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

組建檢查的用途：

  • 在執行組建前驗證您的 Dockerfile 和組建選項。
  • 確保您的 Dockerfile 和組建選項符合最新的最佳實踐。
  • 識別 Dockerfile 和組建選項中的潛在問題或反模式 (anti-patterns)。
提示

若要在 Visual Studio Code 中改進 Dockerfile 的 linting、程式碼導航和漏洞掃描，請參閱Docker VS Code 擴充功能。

執行帶有檢查的組建

組建檢查支援於：

調用組建時預設會執行檢查，並在組建輸出中顯示任何違規情況。例如，以下命令會同時建置映像檔並執行檢查：

$ 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，檢查結果會顯示在 Pull Request 的差異檢視中。

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
GitHub Actions build check annotations

顯示更多詳細輸出

普通 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://docs.docker.com.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://docs.docker.com.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 字串。例如：

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

合併錯誤與跳過參數以用於檢查指令

若要同時跳過特定檢查並在發生檢查違規時報錯，請在 Dockerfile 或組建參數的 check 指令中傳遞以分號 (;) 分隔的 skip 和 error 參數。例如：

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" .

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

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

延伸閱讀

有關使用組建檢查的更多資訊，請參閱：

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.