BuildKit 静态检查规则 JSONArgsRecommended 全解析：ENTRYPOINT/CMD 必须使用 JSON 格式的原因与实战-育师

BuildKit 静态检查规则 JSONArgsRecommended 全解析：ENTRYPOINT/CMD 必须使用 JSON 格式的原因与实战

【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit

导读

JSONArgsRecommended是 BuildKit Dockerfile 前端内置的构建检查（build check）规则之一，它强制要求ENTRYPOINT与CMD指令使用 JSON 数组（exec 形式）而非 shell 字符串（shell 形式）书写参数。这是因为 shell 形式会让程序作为 shell 的子进程运行，无法正确接收SIGTERM、SIGKILL等操作系统信号，从而在容器停止、滚动更新等场景下引发进程无法优雅退出的问题。本文将从规则定义、底层触发逻辑、信号与 PID 1 原理、官方推荐的解决方案以及如何配置跳过/升级为错误等多个层面，完整讲解这条规则，帮助你在使用 BuildKit 构建镜像时写出信号安全、行为可预测的 Dockerfile。

规则概览：警告内容与规则定位

当 BuildKit 在解析 Dockerfile 时发现CMD或ENTRYPOINT使用了 shell 形式且未显式设置SHELL时，会输出如下警告（警告原文即本规则文档的 Output 部分）：

JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals

在 ruleset.go 中，该规则的定义如下：

RuleJSONArgsRecommended = LinterRule[func(instructionName string) string]{ Name: "JSONArgsRecommended", Description: "JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals", URL: "https://docs.docker.com/go/dockerfile/rule/json-args-recommended/", Format: func(instructionName string) string { return fmt.Sprintf("JSON arguments recommended for %s to prevent unintended behavior related to OS signals", instructionName) }, }

注意Format函数的实现细节：警告文案中的ENTRYPOINT/CMD会被实际触发指令的名称（CMD或ENTRYPOINT）替换。也就是说，如果违规的是CMD，你会看到JSON arguments recommended for CMD ...；如果违规的是ENTRYPOINT，则会看到JSON arguments recommended for ENTRYPOINT ...。这与 dockerfile_check_test.go 中验证的 Detail 字段完全一致：

CMD mycommand→JSON arguments recommended for CMD to prevent unintended behavior related to OS signals
ENTRYPOINT mycommand→JSON arguments recommended for ENTRYPOINT to prevent unintended behavior related to OS signals

该规则是构建检查体系（build checks）的一员。BuildKit 内置了一套预定义规则，用于在构建过程中对 Dockerfile 进行静态分析，linter/docs/_index.md 中说明：检查以一次构建调用的方式运行，但它不产出构建结果，而是执行一系列校验，确认你的构建没有违反任何规则。运行方式是在构建命令后追加--check标志：

$ docker build --check .

问题根源：shell 形式与 exec 形式在信号传递上的本质差异

ENTRYPOINT和CMD都支持两种参数语法（这是规则文档 Description 部分的核心内容）：

shell 形式：CMD my-cmd start（不加方括号，整体作为一条 shell 命令行）
exec 形式：CMD ["my-cmd", "start"]（JSON 数组，第一个元素是可执行文件，其余为参数）

二者在镜像元数据与运行方式上存在决定性差异：

shell 形式会被包装进 shell 执行。在 BuildKit 的 dockerfile2llb 转换器 convert.go 中，withShell函数会把args拼接成一条字符串，追加到平台默认 shell（Linux 上通常为/bin/sh -c）之后：
```
func withShell(img dockerspec.DockerOCIImage, args []string) []string { var shell []string if len(img.Config.Shell) > 0 { shell = slices.Clone(img.Config.Shell) } else { shell = defaultShell(img.OS) } return append(shell, strings.Join(args, " ")) }
```
因此ENTRYPOINT my-program start最终写入镜像配置的 entrypoint 等价于/bin/sh -c my-program start（文档注释原文：# entrypoint becomes: /bin/sh -c my-program start）。
exec 形式直接作为主进程运行。ENTRYPOINT ["my-program", "start"]不会经过任何 shell 包装，my-program直接成为容器内的主进程（PID 1）（文档注释原文：# entrypoint becomes: my-program start）。
信号传递差异。当容器收到来自外部（如docker stop、Kubernetes 终止 Pod）的信号时，信号只会送达 PID 1 进程。使用 shell 形式时，真正的程序是 shell 的子进程，而 shell 默认不会把SIGTERM、SIGKILL等信号转发给子进程。结果是：你的程序根本感知不到操作系统信号，无法执行清理逻辑、无法优雅退出，甚至可能被强制杀死后留下孤儿进程或未刷盘的中间状态。这就是规则文档中反复强调的 "unintended behavior related to OS signals"。

事实依据：上述触发逻辑在 convert.go 的dispatchCmd与dispatchEntrypoint函数中实现，判断条件是c.PrependShell && len(d.image.Config.Shell) == 0，即"使用了 shell 形式"且"当前阶段没有任何显式的 SHELL 定义"时，才触发本规则。

代码示例：触发警告与通过检查的 Dockerfile

❌ 坏示例：ENTRYPOINT 无法接收操作系统信号

FROM alpine ENTRYPOINT my-program start # entrypoint becomes: /bin/sh -c my-program start

这条 Dockerfile 在docker build --check .下会触发JSONArgsRecommended警告。在 dockerfile_check_test.go 中，FROM scratch+ENTRYPOINT mycommand的用例精确验证了这一行为：警告 Level 为 1，行号指向第 3 行（ENTRYPOINT所在行）。

✅ 好示例：ENTRYPOINT 可以接收操作系统信号

FROM alpine ENTRYPOINT ["my-program", "start"] # entrypoint becomes: my-program start

使用 exec 形式后，my-program直接作为容器主进程运行，可以正常接收SIGTERM等信号并按预期响应。

关于 PID 1 的额外职责（重要提示）

规则文档特别提醒：以 exec 形式把程序作为 PID 1 运行后，程序就承担了 Linux 中 PID 1 的特殊职责与行为，例如回收（reap）孤儿子进程。如果程序本身没有实现信号处理或子进程回收逻辑，那么作为 PID 1 运行反而可能带来僵尸进程堆积等新问题。因此在采用 exec 形式的同时，建议确保你的程序：

正确处理SIGTERM（执行优雅退出、清理临时资源）；
正确wait()子进程以回收退出状态，避免僵尸进程；
必要时考虑引入成熟的初始化进程（如 tini / dumb-init）来承担 PID 1 的职责。

仍然需要 shell 功能时怎么办：两种官方解决方案

规则文档明确指出：exec 形式下，shell 的特性——如变量展开、管道（|）、命令链（&&、||、;）——都不可用。如果你确实需要这些 shell 功能，就必须使用 shell 形式。但请注意：这仍然意味着可执行文件作为 shell 的子进程运行，信号问题依旧存在。为此，规则文档给出了两种缓解方案。

方案一：创建 wrapper 启动脚本（推荐）

把启动命令封装进一个入口脚本，然后用 JSON 形式的ENTRYPOINT执行该脚本：

FROM alpine RUN apk add bash COPY --chmod=755 <<EOT /entrypoint.sh #!/usr/bin/env bash set -e my-background-process & my-program start EOT ENTRYPOINT ["/entrypoint.sh"]

这里的ENTRYPOINT是 JSON 格式（✅ 通过检查），而脚本内部可以自由使用后台进程、管道、条件判断等 shell 能力。这样既绕过了JSONArgsRecommended警告，又把复杂的启动逻辑收敛到一个可维护的文件中。

方案二：显式声明 SHELL 指令

规则文档说明：在 Dockerfile 中显式使用SHELL指令指定 shell，可以抑制本警告——因为设置SHELL指令本身就表明"使用 shell 形式是有意为之"。

FROM alpine RUN apk add bash SHELL ["/bin/bash", "-c"] ENTRYPOINT echo "hello world"

方案二背后的源码逻辑

这一行为有明确的源码支撑。在 convert.go 中，警告触发条件为c.PrependShell && len(d.image.Config.Shell) == 0：只有当当前阶段（含继承自FROM <stage>的上游阶段）完全没有SHELL定义时才会告警；一旦显式设置了SHELL（d.image.Config.Shell非空），即认为使用 shell 形式是开发者有意识的选择，不再告警。

dockerfile_check_test.go 用四组用例逐一验证了这一规则：

Dockerfile 片段	是否触发警告
`SHELL ["/usr/bin/customshell"]`+`CMD mycommand`	不触发
`SHELL ["/usr/bin/customshell"]`+`ENTRYPOINT mycommand`	不触发
`FROM scratch AS base`+`SHELL [...]`，`FROM base`+`CMD mycommand`	不触发（SHELL 被继承）
`FROM scratch AS base`+`SHELL [...]`，`FROM base`+`ENTRYPOINT mycommand`	不触发（SHELL 被继承）

注意最后一个场景：即使SHELL定义在上游 stage，通过FROM base继承后，当前 stage 的Config.Shell依然非空，因此 shell 形式不会告警。这说明"显式 SHELL"这一豁免是跨阶段继承生效的。

触发条件的源码级总结

把规则文档的表述与 convert.go 的dispatchCmd/dispatchEntrypoint实现对照，可以归纳出以下判定矩阵：

if c.PrependShell { // 使用了 shell 形式（未使用 JSON 数组） if len(d.image.Config.Shell) == 0 { // 且未显式声明 SHELL // 触发 RuleJSONArgsRecommended } args = withShell(d.image, args) // 无论是否告警，都会用 shell 包装 }

CMD/ENTRYPOINT使用 exec 形式（JSON 数组）→PrependShell为 false，不触发；
使用 shell 形式且未设置SHELL→ 触发警告，且最终Cmd/Entrypoint会被withShell包装成/bin/sh -c <命令行>（或自定义 shell）；
使用 shell 形式但设置了SHELL（本 stage 或继承自上游 stage）→ 不触发，但依然用该 shell 包装执行。

此外，exec 形式写入镜像配置时，convert.go 还会设置ArgsEscaped = true（该字段在 OCI 镜像规范中已废弃，但为兼容 Docker 镜像规范而保留），这也是 exec 形式与 shell 形式在镜像元数据层面的另一个差异。

如何运行检查并解读输出

执行构建检查

$ docker build --check .

该命令会运行全部启用的检查规则（包括JSONArgsRecommended）。你可以在 frontend/dockerfile/docs/rules/_index.md 中查看当前版本支持的完整规则列表。

将警告升级为构建失败

默认情况下，即使检查发现警告，构建仍以零退出码结束。如果希望在警告时让构建失败，可以在 Dockerfile 中使用# check指令（详见 reference.md）：

# check=error=true

[!NOTE] 使用check指令并开启error=true时，建议通过# syntax=指令把 Dockerfile 语法固定到特定版本，否则未来新增检查规则时，你的构建可能会意外开始失败。

跳过某条规则

如果某些ENTRYPOINT/CMD确实需要 shell 形式（例如配合SHELL已显式声明、或使用 wrapper 脚本不便改造的场景），可以在对应指令前使用# check=skip注释跳过本规则：

FROM scratch # check=skip=JSONArgsRecommended CMD mycommand

同时跳过多条规则时用逗号分隔：

# check=skip=JSONArgsRecommended,StageNameCasing

跳过全部规则：

# check=skip=all

组合"跳过 + 报错"两种选项时，使用分号分隔：

# check=skip=JSONArgsRecommended;error=true

这些选项的解析实现在 linter.go 的ParseLintOptions中：选项以;分割，支持skip（可指定all或规则名逗号列表）、experimental（启用实验性规则）、error（布尔值）三类；Dockerfile 中的# check注释则通过WithMergedConfigFromComments（linter.go）逐条解析并合并进 lint 配置。dockerfile_check_test.go 也验证了# check=skip=JSONArgsRecommended对CMD和ENTRYPOINT均能正确抑制警告。

实践建议总结

默认使用 exec 形式：ENTRYPOINT/CMD一律写成["可执行文件", "参数1", ...]，让程序作为 PID 1 直接接收信号；
程序需适配 PID 1 职责：实现SIGTERM优雅退出与子进程回收，必要时引入 tini 等 init 进程；
需要 shell 功能时优先用 wrapper 脚本：把复杂启动逻辑放进/entrypoint.sh，再用 JSON 形式ENTRYPOINT ["/entrypoint.sh"]执行；
确认有意使用 shell 形式时显式声明SHELL：SHELL ["/bin/bash", "-c"]既能让行为可预期，也能抑制本警告；
用docker build --check .纳入 CI：结合# check=error=true让违反规则（包括JSONArgsRecommended）的构建直接失败，把信号安全问题消灭在构建阶段。