HTMLHint是SSG项目中唯一能稳定校验生成HTML合规性的工具，必须作用于_build后_的.html文件而非源模板，关键规则包括alt-require、id-unique、tag-pair等，需在CI/CD的build后、deploy前执行并失败中断。
静态站点生成（SSG）项目里，HTML 代码质量监控不能靠人工肉眼检查，必须嵌入构建流程——HTMLHint 是目前唯一能稳定覆盖纯 HTML 文件结构、可访问性和语义规范的工具。
为什么 SSG 构建后还要单独检查 HTML？
静态生成器（如 Eleventy、Hugo、Astro）只保证模板渲染不出错，不校验输出 HTML 是否合规。常见问题包括：img 缺 alt、id 重复、form 缺 label、自闭合标签误写为
<br>（没斜杠）、
doctype 被模板引擎意外删掉等。这些错误在浏览器里可能“看起来正常”，但影响 SEO、无障碍和长期维护。
- 构建产物是最终交付物，
HTMLHint必须作用于生成后的.html文件，而非源模板（如.njk或.md） - 不要在构建前对模板文件运行
HTMLHint：它无法理解 Liquid、Nunjucks 等语法，会把{{ content }}当成非法标签报错 - CI/CD 中建议在
build后、deploy前执行检查，失败则中断发布
如何让 HTMLHint 检查生成后的 HTML 文件
关键在于路径和时机：直接指向 _site/、dist/ 或 public/ 目录（取决于你的 SSG 输出目录），而不是源码目录。
- 命令行运行：
npx htmlhint _site/**/*.html（注意 glob 需 shell 支持，Windows 用户建议用htmlhint "_site/**/*.html"加引号） - 若用 npm script，写成：
"lint:html": "htmlhint dist/**/*.html"，确保dist是你实际的输出目录名 - 配合
htmlhint --format=unix可输出带行号的简洁格式，方便 CI 日志定位 - 避免全局安装
htmlhint：不同项目可能依赖不同规则版本，本地npx更可靠
哪些规则对 SSG 项目最关键
SSG 场景下，以下规则失效风险高、影响直接，建议显式启用：
立即学习“前端免费学习笔记（深入）”；
-
alt-require：所有img必须有alt，SSG 模板中常漏掉动态图片的描述 -
id-unique：生成多页时，模板里硬编码的id="main"可能被重复插入多个页面，导致 JS 选择器失效 -
tag-pair：尤其防div嵌套过深或模板条件分支导致标签未闭合（如{% if x %}<div>{% endif %}） <li> <code>attr-no-undefined：检查data-属性是否拼错，SSG 中常用于传递元数据，拼错后 JS 读不到 - 禁用
doctype-first如果你用的是 Astro 或 Next.js 的 App Router —— 它们默认不输出<!DOCTYPE html>，而是由运行时注入 - CI 环境中工作目录可能不是项目根目录，
htmlhint命令需用绝对路径或先cd进入正确目录再执行 -
.htmlhintrc文件必须放在项目根目录，且配置中"rules"是对象，不是数组；写成"rules": ["alt-require"]会静默失败 - Eleventy 用户注意：
eleventy --dryrun不生成真实 HTML，HTMLHint检查会报“no files found”，必须等eleventy实际构建完成 - Webpack + html-webpack-plugin 场景下，插件生成的 HTML 在内存中，
HTMLHint无法扫描，得改用插件钩子或输出到磁盘后再检查
集成到构建流程容易踩的坑
很多人以为加个 npm script 就完事，结果在 CI 上跑不通，核心问题就两个：路径错、规则没生效。
真正难的不是配置规则，而是让检查发生在正确的时间点、正确的文件上，并且失败时能清晰暴露哪一行 HTML 出了问题——这需要把 HTMLHint 当作构建流水线里的一个“质检闸机”，而不是开发时随手敲的命令。
