直接用 htmlhint 命令行不够用，因其无法适配团队多目录结构（src/、templates/、public/）及不同环境（开发跳过、ci 强制失败、pr 只报告），且缺乏上下文识别、统一输出和 package.json 集成能力；需封装为可复用 cli 工具，通过 bin 注册、编程式调用 api、glob 扫描、json 输出、共享配置及兼容性处理（如 vue 模板提取、windows 路径、esm 限制）实现跨技术栈与环境的一致校验。
为什么直接用 htmlhint 命令行不够用
因为团队项目不是单文件验证，而是要覆盖 src/、templates/、public/ 多目录结构，还要区分开发环境跳过校验、CI 环境强制失败、PR 场景只报告不中断。原生命令 htmlhint "**/*.html" 无法自动识别这些上下文，更没法统一输出格式或集成到 package.json 脚本里做标准化入口。
如何封装成可复用的团队 CLI 工具
核心是把校验逻辑抽离为独立可执行模块，而非每次在 package.json 里硬写命令。推荐用 bin 字段注册本地 CLI：
- 新建
bin/html-check.js，以#!/usr/bin/env node开头，加载htmlhintAPI（非 CLI）进行编程式调用 - 读取
process.argv解析--fix、--ci、--quiet等开关，不同模式走不同规则集（例如 CI 模式启用id-unique+alt-require，本地开发默认关闭） - 用
glob库扫描路径，支持排除node_modules和构建产物目录（如dist/），避免误报 - 错误输出统一为 JSON 格式（含
file、line、ruleId、message），方便后续接入 SARIF 或 IDE 插件
html-check 在 package.json 中的标准化用法
不要让每个项目自己拼 npx htmlhint，而是统一声明为团队脚手架标配命令：
- 在
package.json的bin字段注册："html-check": "./bin/html-check.js" - 所有项目共用同一套
htmlhint-config-team.json，放在公司私有 npm 包里，通过npm install @org/htmlhint-config --save-dev引入 -
scripts中定义："check:html": "html-check --config node_modules/@org/htmlhint-config/htmlhint.json" - CI 配置中直接调用：
npx html-check --ci，失败时自动退出码非 0，触发流水线中断
容易被忽略的兼容性陷阱
HTMLHint 默认不校验内联 <template></template> 或 v-html 绑定内容，但 Vue/React 项目里大量存在。必须手动扩展规则：
- 启用
attr-validate规则，并配合自定义正则匹配v-html=".*?"类表达式，防止 XSS 风险漏检 - 对
.vue文件，需先用@vue/compiler-sfc提取 template 内容，再喂给 HTMLHint —— 直接传**/*.vue会因语法报错中断 - Windows 下路径分隔符为
\，glob默认行为可能不一致，建议显式指定glob.sync("**/*.html", { windowsPathsNoEscape: true }) -
htmlhint不支持 ESM 导入，若 CLI 主文件用了import，需加"type": "module"并确保 Node 版本 ≥14.18
真正难的不是跑通一次校验，而是让不同技术栈（Vue/React/纯 HTML）、不同操作系统、不同 IDE 的成员，在任意时间点执行 npm run check:html 都得到完全一致的结果和错误定位精度。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
