GitLab CI中HTML代码质量检查的核心是htmlhint输出CodeClimate兼容JSON格式，需用--format=codeclimate参数生成codequality.json，并在CI配置中声明artifacts和code_quality报告路径，确保路径为相对路径且作业工作目录为项目根目录。
GitLab CI 中跑 HTML 代码质量检查，核心就一条：用 htmlhint 做静态扫描，但必须输出 GitLab 能识别的格式，否则报告不显示、问题不标记、MR 里看不到红线 —— 这是绝大多数人卡住的第一步。
htmlhint 怎么输出 GitLab 可解析的 JSON 报告
GitLab 的「代码质量」功能只认一种 JSON 结构（CodeClimate 兼容格式），htmlhint 默认不生成这个。直接运行 npx htmlhint **/*.html 会打印人类可读文本，CI 流水线里根本没法提取问题。
- 必须加
--format=codeclimate参数，例如：npx htmlhint src/**/*.html --format=codeclimate > codequality.json - 输出文件名必须是
codequality.json（硬编码路径，不能改） - 确保
codequality.json在作业结束前存在，且不是空文件（空数组[]也算有效） - 如果项目用了自定义规则（
.htmlhintrc），确认该文件在 CI 环境中能被正确加载（建议放项目根目录，不要嵌套太深）
GitLab CI 配置里哪些字段不能漏
光生成 codequality.json 不够，CI 作业必须显式声明 artifact 和 report 类型，否则 GitLab 不知道该拿它干什么。
-
artifacts:下必须包含codequality.json，且设expire_in: 1 week（否则默认 1 小时后删掉，MR 页面刷不出来） -
coverage:不要填 —— 这是给测试覆盖率用的，HTML 检查没这玩意，填了反而报错 -
code_quality:必须作为顶级 key 出现在 job 定义里（不是缩进在 script 下面），值为codequality.json - 整个 job 最好设
allow_failure: false，否则 lint 失败也不阻断 MR 合并，失去检查意义
为什么 MR 里看不到 HTML 错误高亮
常见原因不是规则没生效，而是 GitLab 没法把 report 里的问题锚定到具体行 —— 这通常因为 codequality.json 里缺失 location 字段或路径不匹配。
立即学习“前端免费学习笔记（深入）”；
- 检查
codequality.json中每个 issue 的location.path是否是相对路径（如src/index.html），不能是绝对路径或带./前缀 - 确保 CI 中执行
htmlhint的工作目录是项目根目录（before_script: cd $CI_PROJECT_DIR可强制） - 如果用了 glob（如
**/*.html），某些版本htmlhint会把路径解析成/builds/xxx/src/index.html，这种绝对路径 GitLab 无法映射，得用--cwd显式指定基准目录 - GitLab Pages 或 review app 生成的临时路径（如
public/）别往htmlhint里扫 —— 那是构建产物，不是源码
真正难的不是跑通命令，而是让每一条 warning 都精准落到 MR 的 diff 行上。路径对不上、JSON 格式差一个字段、artifact 没声明 —— 任意一个环节断掉，整个质量检查就变成后台日志里的静默输出。
