将HTML代码质量规范转化为自动化CI规则的实践

HTMLHint需显式启用tag-pair、attr-lowercase等核心规则并置于项目根目录的.htmlhintrc中，否则无法拦截标签未闭合、属性大小写混用等低级错误；CI中须配置SARIF输出、set -e或|| exit 1确保失败中断流程。

HTMLHint怎么配置才能真正拦住低级错误

HTMLHint不是装上就起作用的，它默认规则太宽松，tag-pair、attr-lowercase这些基础项必须显式启用，否则连 <div></div> 这种大小写混用都报不出来。

关键配置点：

• .htmlhintrc 必须放在项目根目录，且不能被 .gitignore 忽略
• 禁用默认宽松模式：删掉或注释掉 "rules": {} 里的 "*": true 这类通配启用
• 强制要求 doctype-first 和 lang-require，否则 标签缺 lang 不会报错
• 对模板类文件（如 .njk、.php）需额外加 "file-ext": ["html", "njk", "php"]

GitHub Actions里HTMLHint失败时为什么不中断流水线

常见现象是 npx htmlhint "**/*.html" 报错后流程仍继续，根本原因是 shell 默认遇到非零退出码不终止。CI 脚本里没加 set -e 或没处理命令返回值。

正确写法：

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

• 用 run: npx htmlhint "**/*.html" 单独成 step，别和 npm install 合并在一行
• 加 if: always() 会导致失败也被忽略，必须删掉
• 若要兼容部分文件跳过检查，改用 npx htmlhint src/**/*.html --config .htmlhintrc || exit 1
• 配合 continue-on-error: false（默认就是 false，但显式写出来更安全）

怎么让HTMLHint报告直接显示在PR评论里

纯命令行输出对协作无效，得转成 GitHub 原生支持的 SARIF 格式，否则检查结果只在 Action 日志里滚动，没人看。

实操步骤：

• 安装支持 SARIF 的插件：npm install @htmlhint/sarif-reporter --save-dev
• 运行命令改为：npx htmlhint --format=@htmlhint/sarif-reporter --output=report.sarif.json "**/*.html"
• 在 workflow 中添加 upload-artifact 步骤，并配置 github/code-scanning action 解析 report.sarif.json
• 注意：SARIF 文件必须 UTF-8 编码，BOM 头会导致解析失败

PHP混排HTML文件怎么避免检查失效

直接跑 htmlhint *.php 会把 PHP 标签当非法 HTML 解析，报一堆 php、echo 未闭合的假错误。

两种解法：

• 用 php-cs-fixer 处理 PHP 模板，它内置 HTML 检查逻辑，能识别 <?php ?> 边界
• 或预处理：先用 sed 或 awk 提取纯 HTML 片段再喂给 HTMLHint（不推荐，易漏逻辑）
• 更稳的做法是分层检查——php-cs-fixer 负责 PHP+HTML 混排，htmlhint 只扫纯 .html 文件

混排文件的检查边界容易模糊，别指望一个工具包打天下，按文件类型切分职责才是实际可行的路。