htmlhint 在 Jenkins 中常静默失败，因其默认返回 0 退出码且不输出结构化错误；必须添加 --format=unix、--quiet=false 并用 || exit 1 强制失败判定，同时使用相对路径和确保 .htmlhintrc 存在。
直接在 Jenkins 构建流程里跑 htmlhint 是可行的，但默认不带 HTML 检查能力——Jenkins 本身不解析 HTML，必须靠外部工具驱动，且容易因路径、退出码、报告格式等问题导致构建“假成功”。
为什么 htmlhint 命令行在 Jenkins 里常静默失败
htmlhint 默认遇到问题只输出警告到 stdout 并返回 0 退出码，Jenkins 把它当成“执行成功”，根本不会中断构建或标记为不稳定。这是最常踩的坑。
- 默认行为：即使发现 50 个
id-unique违规，npx htmlhint *.html仍返回0 - Jenkins 的 Shell 步骤只看退出码，不读 stdout/stderr，所以“报错但构建绿了”是常态
- 没配
--format=unix或重定向输出时，Jenkins 控制台日志里可能根本看不到具体哪行出问题
让 htmlhint 真正阻断低质量 HTML 提交
关键不是“跑起来”，而是让 Jenkins 能感知失败并响应。必须显式启用严格模式：
- 在构建步骤中用：
npx htmlhint --format=unix --quiet=false "**/*.html" || exit 1 -
--format=unix输出标准格式（文件:行:列:消息），方便 Jenkins 解析和归档 -
--quiet=false确保所有规则违规都输出（有些规则默认 quiet） -
|| exit 1强制非零退出码——这是 Jenkins 判定失败的唯一依据 - 若项目用 npm script，建议在
package.json里定义："lint:html": "htmlhint --format=unix --quiet=false src/**/*.html"，然后 Jenkins 跑npm run lint:html || exit 1
避免报告路径权限与跨平台陷阱
本地开发能跑通，Jenkins 上却报 ENOENT: no such file or directory？多半是路径写死了。
立即学习“前端免费学习笔记（深入）”；
- 别用绝对路径如
/home/jenkins/workspace/myproj/src——Jenkins agent 环境千差万别 - 统一用相对路径：
npx htmlhint --config .htmlhintrc "src/**/*.html"（前提是.htmlhintrc在 workspace 根目录） - Windows agent 上注意：Glob 模式
**/*.html可能不展开，改用src\**\*.html或先find（Linux）/Get-ChildItem（PowerShell）枚举后传入 - 如果 Jenkins 启用了 Workspace Cleanup 插件，确认没误删
.htmlhintrc——它必须存在，否则htmlhint会退回到内置默认规则（极宽松）
要不要接入 GitHub PR 注释或 Jenkins 报告页
纯命令行够用，但想进一步闭环，得处理两件事：输出结构化、结果可追溯。
- 生成 SARIF：加参数
--format=sarif --output=htmlhint.sarif，再配合 GitHub Actions 的code-scanning或 Jenkins 的Static Analysis Utilities插件消费 - 生成 HTML 报告：
htmlhint本身不产 HTML，需用第三方工具如htmlhint-reporter-html，但注意它不维护已久，更稳的方式是用 Node.js 脚本解析unix输出后生成简易 HTML 表格 - 别依赖 Jenkins 的 “Publish HTML Reports” 插件直接托管
htmlhint原生输出——它只认固定命名和结构，htmlhint的输出不符合
真正卡住人的从来不是“怎么装 htmlhint”，而是退出码语义、路径上下文、以及 Jenkins 对“失败”的机械判定逻辑——这些地方松一点，检查就形同虚设。
