检查您的构建配置

在 Buildx 版本 0.15.0 中引入

构建检查是 Dockerfile 1.8 中引入的一项功能。它允许您验证构建配置并在执行构建之前进行一系列检查。您可以将其视为 Dockerfile 和构建选项的更高级别的 lint 检查，或者构建的试运行模式。

您可以在构建检查参考中找到可用检查的列表以及每个检查的说明。

构建检查的工作原理

通常，当您运行构建时，Docker 会按照您指定的 Dockerfile 和构建选项中的步骤执行构建步骤。使用构建检查，Docker 不会执行构建步骤，而是检查您提供的 Dockerfile 和选项，并报告它检测到的任何问题。

构建检查可用于

在运行构建之前验证您的 Dockerfile 和构建选项。
确保您的 Dockerfile 和构建选项与最新的最佳实践保持一致。
识别 Dockerfile 和构建选项中潜在的问题或反模式。

使用检查进行构建

构建检查在以下版本中受支持：

Buildx 版本 0.15.0 及更高版本
docker/build-push-action 版本 6.6.0 及更高版本
docker/bake-action 版本 5.6.0 及更高版本

调用构建会默认运行检查，并在构建输出中显示任何违规。例如，以下命令同时构建镜像并运行检查

$ 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://docs.dockerd.com.cn/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.dockerd.com.cn/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。您可以配置 Docker，当报告违规时使构建失败，方法是在您的 Dockerfile 中使用check=error=true指令。这将导致在运行构建检查后，在实际构建执行之前构建出错。

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

进一步阅读

有关使用构建检查的更多信息，请参阅：