切换语言

检查您的构建配置

目录
在 Buildx 版本中引入 0.15.0

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

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

构建检查的工作原理

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

生成检查可用于：

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

使用检查构建

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

默认情况下，调用构建会运行检查，并在 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 警告 ，因为指令应使用 JSON 数组语法。CMD

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

更详细的输出

检查警告是否定期显示简洁的消息 包含规则名称、消息和 where 的行号 Dockerfile 来解决问题。如果您想查看更详细的信息 关于检查，您可以使用 flag.例如：docker build--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 |
--------------------

使用标志时，输出包含指向 检查，以及发现问题的 Dockerfile 代码段。--debug

检查构建而不构建

要在不实际构建的情况下运行构建检查，您可以像往常一样使用该命令，但要添加标志。 下面是一个示例：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 |
--------------------

此输出 with 显示检查的详细消息。--check

与常规构建不同，如果在使用该标志时报告了任何冲突，则该命令将退出并显示非零状态代码。--check

验证时生成失败

生成的检查冲突报告为警告，退出代码为 0，由 违约。您可以将 Docker 配置为在违规 reported，使用 Dockerfile 中的指令。这将 导致构建出错：在运行构建检查后，在 实际构建被执行。check=error=true

Dockerfile 文件
1
2
3
4
5

# syntax=docker/dockerfile:1
# check=error=true

FROM alpine
CMD echo "Hello, world!"

如果没有该指令，此 build 将以 退出代码为 0。但是，对于该指令，构建检查冲突会导致 非零退出代码：# check=error=true

$ 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

您还可以通过传递 build 参数在 CLI 上设置 error 指令：BUILDKIT_DOCKERFILE_CHECK

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

跳过检查

默认情况下，所有检查都在构建镜像时运行。如果您想跳过 特定检查，您可以在 Dockerfile 中使用该指令。 该参数采用要跳过的检查 ID 的 CSV 字符串。 例如：check=skipskip

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

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

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

您还可以通过传递 build 来跳过检查 参数，其中包含要跳过的检查 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

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

要跳过特定检查和检查冲突时出错，请将 和 参数（以分号（） 分隔）传递给 Dockerfile 或构建参数中的指令。例如：skiperror;check

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 参考。

要启用所有实验性检查，请将 build argument 设置为 ：BUILDKIT_DOCKERFILE_CHECKexperimental=all

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

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

Dockerfile 文件
# syntax=docker/dockerfile:1
# check=experimental=all

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

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

请注意，该指令优先于该指令，这意味着无论您设置的指令如何，都将运行实验性检查。例如，如果您设置并启用 experimental 检查，则 experimental 检查仍将运行：experimentalskipskipskip=all

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

延伸阅读

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