检查您的构建配置

目录
可用性： 测试版
要求： 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.container.net.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.container.net.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。您可以使用 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

进一步阅读

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

© . This site is unofficial and not affiliated with Kubernetes or Docker Inc.