hadolint

Hadolint

检查 Dockerfile 中的语法错误、最佳实践违规项和嵌入式 shell 脚本问题。检查镜像标签、软件包固定、清理、COPY 与 ADD 的使用、RUN 命令中的 shell 脚本问题以及已弃用的指令。捕获可能导致构建失败或运行时问题的错误。

此技能的功能

1. 检查 hadolint 是否可用；如果缺失，则提供安装指南（优先使用系统二进制文件，其次使用 Docker）。
2. 检测项目专属的 .hadolint.yaml，若不存在则使用合理的默认配置。
3. 检查 Dockerfile，以发现语法、最佳实践和 RUN 命令中的 shell 脚本问题。
4. 报告带有 DL（Dockerfile）和 SC（shell）规则代码的错误，并提供具体修复方法。

安装检查

hadolint --version 2>/dev/null

如果尚未安装，请尝试通过系统安装：

# Apt (Debian/Ubuntu)
sudo apt-get install hadolint

# Homebrew (macOS/Linux)
brew install hadolint

# Direct download (Linux amd64)
wget -O /usr/local/bin/hadolint \
  https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
chmod +x /usr/local/bin/hadolint

如果系统安装失败或不可用，则改用 Docker：

docker run --rm hadolint/hadolint hadolint --version 2>/dev/null

如果系统二进制文件和 Docker 都不可用，请停止操作并报告问题及修复步骤。不要静默跳过检查。

配置检测优先级

1. 项目根目录中的 .hadolint.yaml
2. 主目录中的 .hadolint.yaml（~/.hadolint.yaml）
3. $XDG_CONFIG_HOME/hadolint.yaml（XDG 标准）
4. references/hadolint-config.yaml 中的默认配置

如果不存在项目配置且使用系统二进制文件，请先使用 references 中的默认配置创建临时 .hadolint.yaml，然后再运行检查。使用 Docker 模式时，如果配置文件存在，则将其挂载。

检查工作流

1. Check hadolint installation
   ├─ System binary available → continue
   ├─ Missing → try install
   │   ├─ Install succeeds → continue
   │   └─ Install fails → Docker fallback
   │       ├─ Docker available → continue (Docker mode)
   │       └─ Docker unavailable → fail with remediation
   
2. Detect project config
   ├─ Found .hadolint.yaml → use it
   └─ Not found → use default config from references/
   
3. Run validation
   ├─ System binary:
   │    hadolint Dockerfile
   └─ Docker mode:
        docker run --rm -i hadolint/hadolint < Dockerfile
   
4. Report results
   ├─ Valid → confirm and proceed
   └─ Invalid → show DL/SC errors, suggest fixes, re-validate

检查方法

检查单个 Dockerfile

hadolint Dockerfile

检查多个文件

hadolint Dockerfile Dockerfile.prod Dockerfile.dev

使用显式配置进行检查

hadolint --config .hadolint.yaml Dockerfile

从标准输入进行检查

cat Dockerfile | hadolint -

Docker 回退方式（系统二进制文件不可用时）

docker run --rm -i hadolint/hadolint < Dockerfile

使用配置进行 Docker 回退检查

docker run --rm -i \
  -v "$(pwd)/.hadolint.yaml:/.config/hadolint.yaml" \
  hadolint/hadolint < Dockerfile

错误处理

安装失败

如果无法通过系统软件包管理器安装 hadolint，且 Docker 也不可用，请报告错误并提供修复步骤。不要继续检查。

检查失败

检查失败时，请针对每个错误报告以下信息：

• 文件和行号
• 错误代码（Dockerfile 最佳实践使用 DL 前缀，shell 脚本问题使用 SC 前缀）
• 问题所在
• 具体修复方法

示例：

Validation failed:

1. Dockerfile:1 DL3006 warning: Always tag the version of an image explicitly
   Fix: FROM ubuntu → FROM ubuntu:22.04

2. Dockerfile:3 DL3008 warning: Pin versions in apt-get install
   Fix: apt-get install -y curl → apt-get install -y curl=7.88.1-10+deb12u5

3. Dockerfile:3 DL3009 info: Delete the apt-get lists after installing
   Fix: add && rm -rf /var/lib/apt/lists/* at the end of RUN

4. Dockerfile:4 DL3015 warning: Use --no-install-recommends flag in apt-get install
   Fix: apt-get install -y → apt-get install -y --no-install-recommends

5. Dockerfile:5 DL3020 warning: Use COPY instead of ADD for files
   Fix: ADD https://example.com/app.tar.gz → use curl or wget in RUN

6. Dockerfile:7 DL4000 error: MAINTAINER is deprecated, use LABEL instead
   Fix: MAINTAINER [email protected] → LABEL maintainer="[email protected]"

7. Dockerfile:10 DL4006 warning: Set the SHELL directive in RUN for pipefail
   Fix: add SHELL ["/bin/bash", "-o", "pipefail", "-c"] before RUN with pipes

8. Dockerfile:3 SC2086 info: Double quote to prevent globbing
   Fix: COPY $SOURCE → COPY "$SOURCE"

DL 代码标识 Dockerfile 专属问题。SC 代码来自对 RUN 指令内容执行的 shellcheck。报告错误后，请建议修复方法，并要求修正后重新检查。

规则参考

请参阅 references/hadolint-rules.md，了解完整规则参考、常见错误类别、DL/SC 代码的详细说明、修复示例和配置文件格式。