htmlhint必须嵌入构建流水线早期阶段，在模板渲染完成但html文件未写入磁盘前，对内存中生成的document字符串做即时校验；它不替代prettier格式化，而是专查语义、可访问性与seo问题，如alt缺失、标题唯一性、属性重复等，且需统一ci与本地版本以避免解析差异。
静态站点构建时，HTMLHint 该在哪个环节介入？
HTMLHint 不该等全部页面生成完再跑，那样修复成本高、反馈滞后。它必须嵌入到构建流水线的早期阶段——在模板渲染完成、但 HTML 文件尚未写入磁盘前，对内存中生成的 document 字符串做即时校验。
常见错误现象：用 eleventy 或 astro 时，HTMLHint 报错说 Attribute "class" is not allowed on element "img"，其实是因为模板里写了 <img class="logo"> —— 这不是语法错误，而是规则配置没适配现代 HTML 标准（img 确实支持 class）。
- 推荐做法：在构建脚本中调用
htmlhintCLI 时，传入--config .htmlhintrc，且配置中显式启用attr-bans规则并排除class - 避免把
.htmlhintrc放在根目录却未设htmlhint: { globals: { "htmlhint": true } }，否则部分工具（如prettier-plugin-html）会忽略它 - 若用
astro，直接在astro.config.mjs的onPreBuild钩子中读取renderedHtml字符串，传给HTMLHint.verify()，比扫描输出目录快 3 倍以上
为什么不能只靠 Prettier 格式化就跳过 HTML 质量检查？
Prettier 只管格式，不管语义。它能把 <div><p>hello</p></div> 缩进对齐，但不会告诉你 <div> 里嵌 <code><p></p> 是合法但语义冗余，也不会发现 <button onclick="location.href='x.html'"></button> 这种可访问性灾难。
典型场景：团队用 Markdown 写文档，通过 remark-html 渲染成 HTML。Prettier 对生成的 HTML 无能为力，而 HTMLHint 能捕获 alt 缺失、aria-* 属性拼写错误、或 <h2></h2> 直接跟在 <h4></h4> 后面这类结构问题。
-
prettier默认不校验属性值是否合法（比如role="buton"拼错），htmlhint的attr-validate规则能立刻报错 - 某些静态生成器（如
Hugo）默认开启unsafe模式，允许原始 HTML 插入，这时<script></script>标签可能被意外注入——htmlhint的script-max-length和inline-script规则就是为此设的 - 别把
prettier的printWidth当成质量指标；一行写 200 个 class 名字依然合法，但htmlhint的attr-max-len可以强制拦截
CI 流水线里 HTMLHint 报错但本地不报，怎么快速定位？
根本原因通常是环境差异：本地 Node 版本、HTMLHint 版本、甚至文件换行符（\r\n vs \n）都可能导致解析差异。最常踩的坑是 CI 使用了缓存的 node_modules，而 htmlhint 依赖的 parse5 在 v7.1.0 后对自闭合标签（如 <img>）的处理更严格。
错误信息示例：Parse Error: Unexpected end tag "br" —— 实际是 CI 中 htmlhint 解析器版本更高，把旧写法 <br> 当作非法，而本地仍用 v6.x 兼容模式。
- 统一版本：在
package.json中锁定"htmlhint": "7.2.0"，而非"^7.0.0" - CI 中加一步验证：
npx htmlhint --version输出必须和本地一致，否则清空缓存重装 - 关键路径加
--format=checkstyle输出 XML，供 CI 工具解析；避免用默认格式，因空格/缩进差异会导致文本比对失败
HTMLHint 规则太多，哪些必须开，哪些可以关？
静态站点生成器产出的 HTML 天然规避了大量动态风险（比如没有 eval()、不拼接用户输入），所以不必照搬 CMS 项目的规则集。重点守住语义、可访问性、SEO 基线即可。
容易被忽略的硬性要求：搜索引擎对 <title></title> 长度、<meta name="description"> 存在性极其敏感，而 HTMLHint 默认不查这些。
- 必开：
attr-req-value（防止required写成required=""）、head-title（强制有且仅有一个<title></title>）、attr-no-duplication（防class="a" class="b"） - 建议关：
id-class-ad-disabled（静态站无需防广告 ID）、script-src（除非你真用内联 script）、attr-lowercase（HTML5 不区分大小写，且某些生成器输出大写属性） - 性能相关：开
img-alt-req和img-redundant-alt，但关img-width-height——现代响应式布局下宽高属性反而限制灵活性
<main></main> 缺失，不影响页面显示，但会让屏幕阅读器找不到主内容区——这种问题在生成千页文档时，漏掉一个模板就等于漏掉一百个页面的可访问性保障。
