检查您的构建配置

在 Buildx 版本中引入 0.15.0

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

你可以在构建检查参考中找到可用的检查列表以及每个检查的描述。

构建检查的工作原理

通常，在运行构建时，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.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 显示检查的详细消息。

与常规构建不同，如果在使用--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 在命令行界面设置错误指令：

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

跳过检查

默认情况下，在构建镜像时会运行所有检查。如果要跳过特定检查，可以在 Dockerfile 中使用 check=skip 指令。 skip 参数采用一个 CSV 字符串，其中包含要跳过的检查 ID。例如：

Dockerfile

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

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

构建此 Dockerfile 不会导致任何检查违规。

你还可以通过传递构建参数 BUILDKIT_DOCKERFILE_CHECK 和一个 CSV 字符串来跳过检查，其中包含你想要跳过的检查 ID。例如：

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

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

Dockerfile

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

将检查指令的错误和跳过参数合并

为了同时跳过特定检查并在检查违规时报错，可以在Dockerfile或构建参数中将skip和error参数用分号（;）分隔后传递给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" .

你还可以在Dockerfile中使用check指令启用实验性检查：

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

进一步阅读

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