检查您的构建配置

在 Buildx 版本中引入 0.15.0

构建检查是 Dockerfile 1.8 中引入的一项功能。它允许您验证构建配置，并在执行建。将其视为 Dockerfile 和构建的 linting 的高级形式选项或构建的试运行模式。

您可以在 Build checks 参考中找到可用检查的列表以及每个检查的描述。

构建检查的工作原理

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

生成检查可用于：

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

使用检查构建

构建检查在以下方面受支持：

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

默认情况下，调用构建会运行检查，并在 build 输出。例如，以下命令会生成镜像并运行检查：

$ 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显示简洁的消息包含规则名称、消息和 where 的行号 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/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/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显示检查的详细消息。

与常规 build 不同，如果在使用--checkflag 时，命令将以非零状态代码退出。

验证时生成失败

生成的检查冲突报告为警告，退出代码为 0，由违约。您可以将 Docker 配置为在违规 reported，使用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指令中，此 build 将以退出代码为 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

您还可以在 CLI 上设置 error 指令，方法是将BUILDKIT_DOCKERFILE_CHECKbuild 参数：

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

跳过检查

默认情况下，所有检查都在构建镜像时运行。如果您想跳过特定检查，您可以使用check=skip指令。这skipparameter 接受要跳过的检查 ID 的 CSV 字符串。例如：

Dockerfile 文件

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

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

构建此 Dockerfile 不会发生检查冲突。

您还可以通过传递BUILDKIT_DOCKERFILE_CHECK建参数，其中包含要跳过的检查 ID 的 CSV 字符串。例如：

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

要跳过所有检查，请使用skip=all参数：

Dockerfile 文件

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

组合 error 和 skip 参数用于 check 指令

要跳过特定检查和检查冲突时出错，请将skip和error参数（以分号（）分隔）添加到;check指令或 build 参数中。例如：

Dockerfile 文件

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

Build 参数

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

实验检查

在将检查提升为稳定检查之前，它们可能作为实验性可用检查。默认情况下，实验性检查处于禁用状态。要查看实验性检查可用，请参阅 Build checks 参考。

要启用所有实验检查，请将BUILDKIT_DOCKERFILE_CHECK建 argument 设置为experimental=all:

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

您还可以使用check命令：

Dockerfile 文件

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

要有选择地启用实验性检查，您可以传递检查要启用的 ID，或者选中check指令或作为 build 参数。例如：

Dockerfile 文件

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

请注意，experimental指令优先于skip指令，这意味着实验性检查将运行，而不管skip指令。例如，如果您将skip=all并启用 experimental 检查，则 experimental 检查仍将运行：

Dockerfile 文件

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

延伸阅读

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

检查您的构建配置

APP信息