HTMLHint规则必须在CI流水线早期介入，作为代码合并前的硬性卡点，一旦失败即拒绝PR；需启用doctype-first和meta-charset-require等底线规则，明确检查范围、使用配置文件、禁用ignore注释，并确保错误日志含行号与上下文HTML片段。
HTMLHint规则必须在CI流水线早期介入
HTML代码质量卡点不是“最后检查”，而是要卡在代码合并前的最早环节。一旦 htmlhint 运行失败，PR 就该直接被拒绝——不能靠人工补救，也不能跳过。很多团队把 HTML 检查放在构建后或部署前，结果问题已经进主干，修复成本翻倍。
常见错误现象：htmlhint 在本地能跑通，CI 中却报错；或只对 index.html 检查，漏掉模板目录下的 **/*.html。
- 确保 CI 脚本中明确指定检查范围，例如：
htmlhint "src/**/*.html" "templates/**/*.html" - 使用
.htmlhintrc配置文件而非命令行参数，避免环境差异导致规则不一致 - 把
htmlhint放在 lint 阶段，且必须早于构建（Webpack）和测试（axe-core、link-checker） - 禁用
ignore或disable注释——它们会绕过卡点，等于给质量门禁开后门
doctype-first 和 meta-charset-require 是硬性拦截项
这两个规则不是“建议”，而是浏览器渲染和字符解析的底线。CI 中若允许缺失 <!DOCTYPE html> 或未声明 <meta charset="UTF-8">，后续所有测试、可访问性检查都可能失真——因为页面根本没在标准模式下运行。
使用场景：静态站点生成器（如 Hugo、Jekyll）、多模板项目、CMS 前端输出页。
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
-
doctype-first必须启用，且要求 DOCTYPE 位于文件第一行，前面不能有空格或 BOM -
meta-charset-require要求<meta charset="...">出现在<head>的前 1024 字节内，否则部分浏览器会忽略 - 注意：某些 SSR 框架（如 Next.js）会在运行时注入 meta，但 CI 仍需检查原始模板源码是否含该标签
避免与 axe-core、link-checker 等工具职责重叠
HTMLHint 是结构规范检查，axe-core 是可访问性检测，link-checker 是链接有效性验证——三者目标不同，不能互相替代，也不该混在同一阶段执行。卡点设计混乱会导致失败原因模糊、修复路径断裂。
性能影响：axe-core 启动 Puppeteer 开销大，不适合在 lint 阶段运行；link-checker 依赖网络，应单独设为可选阶段或仅在 nightly job 中执行。
- HTMLHint 卡点只负责：标签大小写、属性重复、闭合配对、doctype/meta 编码等静态语法类问题
- axe-core 应放在 e2e 测试之后、部署前，作为“发布前最后一道可访问性闸门”
- link-checker 若用于生产环境校验，建议用缓存 + 白名单机制，避免因第三方链接失效阻塞整个 CI
- 所有工具输出必须带清晰错误定位（行号+列号），否则开发者无法快速修复
CI 中 HTML 检查失败时，日志必须暴露原始 HTML 片段
只报 error on line 42 不够。开发者需要看到出问题那一行前后 3 行的真实 HTML 内容，否则就得手动 checkout、本地复现、逐行排查——这直接瓦解卡点效率。
容易踩的坑：很多 CI 模板默认截断输出，或把 htmlhint 输出重定向到静默日志，导致错误信息只剩一个退出码。
- 在 CI 脚本中显式启用详细输出：
htmlhint --format=verbose "src/**/*.html" - 若使用 GitHub Actions，确保
run步骤未设置shell: bash -e这类提前退出逻辑，否则错误日志被吞掉 - 对自动生成的 HTML（如文档生成器输出），需额外加
--ignore "**/dist/**"，避免把构建产物也纳入卡点
