Hadolint Dockerfile 语法检查教程

编写 Dockerfile 时，即使语法正确也可能存在不符合最佳实践的问题，例如使用了不安全的指令、镜像层冗余或缺少版本锁定等。Hadolint 是目前最流行的 Dockerfile 静态分析工具，它基于 Dockerfile 最佳实践规则和 ShellCheck 对 Shell 命令的检查，能帮助你在构建之前发现并修复潜在问题。

一、安装 Hadolint

1.1 下载二进制文件

curl -Lo /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
chmod +x /usr/local/bin/hadolint
hadolint --version

1.2 通过 Docker 运行

# 检查当前目录的 Dockerfile
docker run --rm -i hadolint/hadolint < Dockerfile

# 检查指定文件
docker run --rm -i hadolint/hadolint < path/to/Dockerfile

二、基本使用

# 检查 Dockerfile
hadolint Dockerfile

# 指定输出格式
hadolint --format json Dockerfile
hadolint --format codeclimate Dockerfile
hadolint --format sarif Dockerfile

# 仅显示错误和警告（忽略信息级别）
hadolint --failure-threshold warning Dockerfile

三、常见规则解读

Hadolint 的规则以 DL 开头（Dockerfile Lint）或 SC 开头（ShellCheck）。以下是最常见的规则：

DL3006 - 总是使用标签指定基础镜像版本

# 违反规则
FROM ubuntu

# 修正
FROM ubuntu:22.04

DL3008 - 锁定 apt 安装包版本

# 违反规则
RUN apt-get install -y curl

# 修正（锁定版本确保构建可重复）
RUN apt-get install -y curl=7.88.1-10+deb12u5

DL3009 - 删除 apt 缓存

# 违反规则
RUN apt-get update && apt-get install -y curl

# 修正
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

DL3015 - 使用 --no-install-recommends

# 违反规则
RUN apt-get install -y nginx

# 修正（避免安装不必要的推荐包）
RUN apt-get install -y --no-install-recommends nginx

DL3025 - 使用 JSON 格式的 CMD

# 违反规则（shell 格式）
CMD npm start

# 修正（exec 格式，信号传递正确）
CMD ["npm", "start"]

DL4006 - 设置 SHELL 使用 pipefail

# 违反规则
RUN curl https://example.com | sh

# 修正
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN curl https://example.com | sh

四、自定义配置

创建 .hadolint.yaml 配置文件来自定义规则：

cat > .hadolint.yaml <<'EOF'
# 忽略特定规则
ignored:
  - DL3008  # 不强制锁定 apt 包版本
  - DL3013  # 不强制锁定 pip 包版本

# 设置受信任的基础镜像仓库
trustedRegistries:
  - docker.io
  - gcr.io

# 设置严重级别覆盖
override:
  warning:
    - DL3042  # 将此规则从 error 降为 warning

# 标签规则
label-schema:
  maintainer: text
  version: semver
EOF

4.1 在 Dockerfile 中内联忽略规则

# hadolint ignore=DL3008,DL3009
RUN apt-get update && apt-get install -y curl nginx

五、CI/CD 集成

5.1 GitHub Actions

cat > .github/workflows/hadolint.yml <<'EOF'
name: Hadolint
on: [push, pull_request]
jobs:
  hadolint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: hadolint/hadolint-action@v3.1.0
      with:
        dockerfile: Dockerfile
        failure-threshold: warning
EOF

5.2 Git Pre-commit Hook

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/bash
if [ -f Dockerfile ]; then
    echo "Running Hadolint..."
    hadolint Dockerfile
    if [ $? -ne 0 ]; then
        echo "Hadolint found issues. Please fix before committing."
        exit 1
    fi
fi
EOF
chmod +x .git/hooks/pre-commit

六、批量检查项目中的所有 Dockerfile

# 查找并检查所有 Dockerfile
find . -name "Dockerfile*" -exec echo "=== Checking {} ===" \; -exec hadolint {} \;

# 使用脚本批量检查
cat > /opt/check-dockerfiles.sh <<'EOF'
#!/bin/bash
EXIT_CODE=0
for df in $(find . -name "Dockerfile*" -not -path "./.git/*"); do
    echo "Checking: $df"
    hadolint "$df"
    if [ $? -ne 0 ]; then
        EXIT_CODE=1
    fi
done
exit $EXIT_CODE
EOF
chmod +x /opt/check-dockerfiles.sh

七、与编辑器集成

Hadolint 支持与主流编辑器集成，在编写 Dockerfile 时实时提示：

VS Code：安装 hadolint 扩展，保存时自动检查。
Vim/Neovim：通过 ALE 或 coc.nvim 集成 Hadolint。
Sublime Text：使用 SublimeLinter-hadolint 插件。

总结

Hadolint 是保证 Dockerfile 质量的重要工具，建议在开发流程中集成使用。配合 Dive 镜像分析和 Trivy 漏洞扫描，可以构建出高质量、安全的 Docker 镜像。更多 Dockerfile 编写技巧请参考 Dockerfile 最佳实践指南。选购搬瓦工 VPS 请访问 bwh81.net，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。