检查你的构建配置

目录
可用性： 测试版
要求： Docker Buildx 0.15.0 及更高版本

构建检查是 Dockerfile 1.8 中引入的一项特性。它允许你在执行构建之前验证构建配置并进行一系列检查。可以将其视为 Dockerfile 和构建选项的高级 linting 形式，或者构建的空运行模式。

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

构建检查的工作原理

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

构建检查对于以下方面非常有用：

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

提示

想要更好的 VS Code 中的 Dockerfile 编辑体验？请查看 Docker VS Code 扩展（测试版），用于 linting、代码导航和漏洞扫描。

使用检查进行构建

构建检查支持以下版本：

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

$ 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.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。你可以通过在 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 上设置 error 指令

$ 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 构建参数，并在其后跟一个要跳过的检查 ID 的 CSV 字符串来跳过检查。例如

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

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

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

结合使用 check 指令的 error 和 skip 参数

要同时跳过特定检查并在检查违规时出错，请在 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 的 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

进一步阅读

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

页面选项