HTML项目采用Stylelint与HTMLHint联合校验的方法

Stylelint 和 HTMLHint 职责分离：Stylelint 专检 <style> 块（需 postcss-html 解析器）和内联样式（不支持），HTMLHint 专检标签闭合、属性规范等结构问题；二者必须独立配置、分别运行，不可替代。

Stylelint 和 HTMLHint 不能互相替代，必须分开配置、分别运行；HTML 中的 <style> 块和内联 style 属性由 Stylelint 负责，HTML 结构和属性规范由 HTMLHint 负责。

为什么 Stylelint 会报 Cannot parse selector 或 Unknown word

这类错误几乎全是解析器不匹配导致的。Stylelint 默认只认纯 CSS 文件，遇到 <style> 块或 style="..." 时，若没指定对应语法解析器，就会把整段当无效 CSS 处理。

• 在 .stylelintrc.js 中必须显式启用 postcss-html 解析器，并绑定到 HTML/Vue 文件： overrides: [{ files: ["**/*.html", "**/*.htm"], customSyntax: "postcss-html", extends: ["stylelint-config-html"] }]
• Vue 项目还要加 "**/*.vue" 并换用 stylelint-config-html/vue
• 漏写 customSyntax 或拼错包名（比如写成 postcss_html），都会让 Stylelint 退回到默认 CSS 解析器，立刻报错

HTMLHint 的 tag-pair 规则为何总报错但浏览器能正常渲染

因为浏览器做了容错修复，而 HTMLHint 检查的是原始源码结构。它不关心最终 DOM，只校验标签开闭逻辑是否合法。

• tag-pair 默认开启，会精准定位到第几行第几列，比如 <div><p>text</div> 中 </div> 行会报 “Tag must be paired”
• 自闭合标签如 <img> 不触发该规则——它只管“有开无闭”或“闭多于开”，不管是否加斜杠
• 混用 Pug/JSX 模板时，部分文件不是完整 HTML，需临时禁用："tag-pair": false，否则大量误报
• 命令行调试可临时关闭单条规则：npx htmlhint --rules tag-pair:false index.html

GitLab CI 中如何让两者都失败时阻断部署

两个工具必须独立执行，且任一失败都应使 pipeline 中断。不能合并成一条命令，也不能忽略退出码。

立即学习“前端免费学习笔记（深入）”；

• 在 .gitlab-ci.yml 的 test 阶段写两行脚本，顺序无关，但都必须用 && 连接确保失败即停：
  npx htmlhint "src/**/*.html" && npx stylelint "**/*.html" "**/*.css"
• 注意 shell 通配符问题：**/*.html 必须用双引号包裹，否则在某些 GitLab Runner 环境下会被提前展开失败
• 如果项目含 Vue，Stylelint 命令里要加上 "**/*.vue"，否则 <style> 块不会被检查
• HTMLHint 不支持直接校验 Vue 文件，需靠 eslint-plugin-html 或在 Vue 模板中只保留标准 HTML 片段

最容易被忽略的是：Stylelint 对 HTML 的支持完全依赖 customSyntax 和 extends 的组合，缺一不可；而 HTMLHint 的规则生效前提是配置文件必须放在项目根目录且命名为 .htmlhintrc，放错位置或改名就等于没配。