必须拦截三类错误：doctype 缺失或位置错误、meta charset 缺失或不在 head 前 1kb 内、img 缺 alt 属性且非装饰图，以及非法标签嵌套；仅启用 htmlhint 5 条核心规则并结合 git hook 轻量集成。
微小团队不需要照搬大厂整套 HTML 质量规范，但必须守住几条“不踩就不出事”的底线。真正卡点的不是规则数量，而是哪些错误一旦出现，会立刻导致渲染异常、SEO 失效或无障碍访问崩溃。
哪些 HTML 错误必须拦截？
不是所有 warning 都值得卡住提交。只拦三类：破坏 DOM 结构、阻断可访问性、违反基础协议。
-
DOCTYPE缺失或位置错误 —— 浏览器进 quirks mode，CSS 盒模型、Flex 行为全乱 -
<meta charset="UTF-8">缺失或不在前 1KB 内 —— 中文乱码、表单提交字段值截断 -
<img>缺alt属性且非装饰图 —— 屏幕阅读器报错、Lighthouse 可访问性直接扣分 - 标签嵌套非法，如
<p></p> <div></div>—— 浏览器自动修正 DOM，JS 获取元素位置/尺寸出错
用 HTMLHint 做最小可行检查
别配 30 条规则。只启用 5 条核心规则，加一个自定义白名单，就能覆盖 90% 真实问题。
在项目根目录建 .htmlhintrc：
{
"rules": {
"doctype-first": true,
"meta-charset-require": true,
"tagname-lowercase": true,
"attr-lowercase": true,
"attr-quote-style": "double"
},
"files": ["**/*.html"]
}
说明：
-
doctype-first和meta-charset-require是硬性卡点，不通过就拒绝 commit -
tagname-lowercase和attr-lowercase防止大小写混用引发模板引擎解析歧义（尤其搭配 Vue / JSX 使用时） -
attr-quote-style统一用双引号，避免href='javascript:void(0)'这类单引号里嵌单引号的语法陷阱
怎么集成到日常流程里不添堵？
微小团队没人力维护 CI 流程，靠 git hook + lint-staged 就够用，且只对改动文件检查。
安装依赖：
npm install --save-dev htmlhint lint-staged husky
配置 package.json：
"lint-staged": {
"*.html": "htmlhint"
},
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
}
关键细节：
- 不要全局监听所有
.html文件，只查git add进暂存区的那些 —— 避免老代码报错拖慢提交 - 不加
--quiet或--format=compact，默认输出带行号，开发者一眼定位问题 - 如果某页面确实要绕过（比如第三方生成的统计页），在对应文件顶部加注释：
<!-- htmlhint disable -->
语义化和 ARIA 不是卡点，是长期习惯
像 <nav></nav> 替换 <div class="nav">、给按钮加 <code>aria-label 这类改进，不适合设为强制拦截项 —— 它们不影响即时功能，但长期积累能显著降低维护成本。
建议做法：
- 把语义化标签对照表贴在团队共享文档首页（
<header></header>/<main></main>/<aside></aside>各什么场景用） - 每次 Code Review 时，只问一句：“这个容器有没有更合适的语义标签？” —— 不打回，但记入 review comment
- 用 Chrome 的 Lighthouse 手动跑一次“Accessibility”审计，把结果截图发群，比讲规范更直观
真正难的不是写对规则，而是让团队在没专职 QA 的情况下，自然养成“改完 HTML 就顺手看一眼控制台有没有 parser error”的肌肉记忆。
