自研脚手架集成 HTML 质量检查需统一使用项目根目录 .htmlhintrc 配置，严格绑定 pre-commit 钩子与 CI 流程，确保规则生效、错误可追溯、失败即阻断，并按项目类型预置差异化规则。
自研脚手架里集成 HTML 质量检查，不是“加个插件就完事”，而是得让 htmlhint 的执行时机、配置粒度、错误反馈路径都贴合你团队的真实提交和构建节奏——否则它很快就会被 npm run lint 里跳过的那行注释绕过去。
htmlhint 配置必须绑定到项目根目录的 .htmlhintrc，不能靠 --config 临时指定
很多人在脚手架里用 npx htmlhint src/**/*.html --config ./configs/htmlhint.json 启动检查，看似灵活，实则埋雷：CI 环境里路径可能错位；开发时本地改了配置但没 commit，导致本地通过、CI 失败；更麻烦的是，htmlhint 的 attr-lowercase 这类规则对自定义属性（如 data-xxx）默认不生效，除非配置里显式启用 attr-lowercase: { "except": ["data-*"] }。
正确做法是统一用项目根目录下的 .htmlhintrc，且必须包含：
-
"attr-lowercase": true—— 否则 React/Vue 模板里混写的DATA-ID或ngIf会漏检 -
"tag-pair": true—— 防止<div><span></span></div>这类嵌套错位在 SSR 渲染时出问题 -
"id-unique": true—— 动态生成的组件（如列表项）若复用相同id，会影响无障碍读屏和 JS 查询
pre-commit 钩子里跑 htmlhint，但要排除 node_modules 和构建产物目录
把 htmlhint 塞进 pre-commit 是最有效的防线，但直接 npx htmlhint "**/*.html" 会扫描 dist/ 或 build/ 下的生成文件，既慢又无意义，还可能因压缩后 HTML 格式异常报错。
立即学习“前端免费学习笔记（深入）”；
在 .pre-commit-config.yaml 中应这样写：
repos:
- repo: local
hooks:
- id: htmlhint
name: HTML code quality check
entry: npx htmlhint
types: [html]
files: ^(src|public|templates)/.*\.html$
pass_filenames: true注意三点：
-
files正则限定作用域，避免扫到node_modules或 CI 自动生成的报告页 -
types: [html]依赖 pre-commit 的类型识别，比单纯靠扩展名更可靠 - 别用
args传--quiet——开发者需要看到具体哪一行、哪个规则失败，否则没人愿意修
CI 流程中 htmlhint 必须失败即中断，且输出 SARIF 格式供 GitHub Code Scanning 解析
GitHub Actions 里只写 npx htmlhint "**/*.html" || echo "done" 是自欺欺人。CI 的核心价值在于“阻断劣质代码进入主干”，所以必须让检查失败时整个 job 退出码非 0。
同时，原生 htmlhint 输出是纯文本，GitHub 的 Code Scanning 不认。得加 --format=sarif 并重定向到文件：
- name: Run HTMLHint (SARIF)
run: |
npx htmlhint . --format=sarif --output=htmlhint-results.sarif || exit 1
shell: bash后续再接 actions/upload-artifact 和 github/codeql-action/upload-sarif，才能让问题直接出现在 PR 的 “Code scanning alerts” tab 里。漏掉 || exit 1 或格式不对，等于白跑。
脚手架 CLI 初始化时，.htmlhintrc 应根据项目类型预置差异化规则
一个全栈项目和一个纯静态官网，HTML 质量关注点完全不同：前者要严控 script 标签位置（防阻塞渲染）、meta 编码声明；后者可能允许内联样式或省略 alt（图库类页面）。
脚手架初始化命令（如 create-myapp --template=ssr）应自动写入不同版本的 .htmlhintrc：
- SSR 模板：启用
"script-placement": ["head", "body"]和"meta-charset-require": true - 静态站点模板：放宽
"alt-require": false，但强制"doctype-first": true - 微前端子应用模板：禁用
"id-unique"（由主应用统一分配 ID），但加"attr-no-duplication": true
硬编码一套通用规则，不如不做——团队很快就会在 // htmlhint-disable-line 上达成默契，然后集体绕过。
