檢查您的構建配置

目錄
可用性： 測試版
要求： Docker Buildx 0.15.0 及更高版本

構建檢查是 Dockerfile 1.8 中引入的一項功能。它允許您在執行構建之前驗證您的構建配置並進行一系列檢查。可以將其視為 Dockerfile 和構建選項的高階 linting 形式，或者是構建的空執行模式。

您可以在構建檢查參考中找到可用檢查列表及其說明。

構建檢查的工作原理

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

構建檢查對於以下方面很有用

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

為了改進 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，檢查會顯示在拉取請求的 diff 檢視中。

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.net.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.net.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 不會導致任何檢查違規。

您還可以透過傳遞 BUILDKIT_DOCKERFILE_CHECK 構建引數，其中包含您要跳過的檢查 ID 的逗號分隔字串來跳過檢查。例如

$ 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 字串傳遞給 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

進一步閱讀

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