sonarqube 默认不扫描html文件，因其不被视为一级语言且默认规则极少；需显式配置sonar.sources、sonar.inclusions，并在html quality profile中激活a11y/seo/语义等规则，配合sonar-javascript-plugin≥10.0解析内嵌js。
SonarQube 默认对 HTML 的支持有限，它不把 HTML 当作“可执行语言”处理，而是作为模板/标记语言做轻量级检查。想靠默认规则准确度量 HTML 代码健康度——比如语义正确性、无障碍（a11y）、SEO 友好性、结构冗余或内联脚本风险——基本做不到。
必须定制规则，且得从两个层面动手：**规则激活 + 扫描器配置增强**，缺一不可。
HTML 文件为什么扫不出问题？
常见现象：sonar-scanner 运行成功，但 HTML 文件下零问题、零覆盖率、零重复率指标；SonarQube UI 里 HTML 文件甚至不显示在“文件列表”中。
根本原因：SonarQube 默认只启用极简的 HTML 规则集（如 html:NoScriptTag），且不自动识别 .html 或 .htm 为源码类型——除非你显式声明。
关键点：HTML 不是 sonar.language 的一级支持语言，它被归入 web 分类，依赖插件和显式路径匹配。
-
SonarQube10.x+ 已移除原生sonar.web插件，改由sonar-javascript-plugin兼容解析 HTML 中的<script></script>块，但忽略纯结构 - 若未配置
sonar.sources显式包含.html，扫描器直接跳过这些文件 - 默认 Quality Profile 对 HTML 几乎不加载任何活跃规则（查
Quality Profiles → HTML → Active Rules就知道）
如何让 HTML 进入扫描范围并触发检查？
不是加个 sonar.language=html 就完事——这个参数在新版已废弃，且 HTML 不支持独立 language 值。
正确做法是组合三要素：
- 在
sonar-project.properties中明确列出 HTML 路径：sonar.sources=src/main/webapp,src/main/resources/templates,public（确保含.html文件的目录） - 强制声明文件后缀：
sonar.inclusions=**/*.html,**/*.htm（sonar.exclusions里别误 exclude 掉） - 启用 HTML 相关插件规则：登录
SonarQube Web UI→Quality Profiles→ 切换到HTML类型 Profile → 点击Activate more rules→ 搜索关键词如a11y、seo、semantic、inline-script，逐条激活（例如Web:HtmlElementShouldHaveAlt、Web:HtmlFormShouldHaveLabel）
注意：sonar-javascript-plugin 版本需 ≥ 10.0（对应 SonarQube 10.5+），否则 HTML 内嵌 JS 不会被解析，相关规则（如 javascript:S1134 在 script 标签里触发）会失效。
哪些 HTML 规则值得优先激活？
别全开——很多规则依赖运行时上下文（如 DOM 结构、CSS 加载顺序），静态扫描易误报。聚焦高价值、低噪音的结构性与可访问性规则：
-
Web:HtmlElementShouldHaveAlt：强制<img>含alt，无障碍基础项 -
Web:HtmlFormShouldHaveLabel：表单控件缺失关联<label></label>，影响屏幕阅读器 -
Web:HtmlPageShouldHaveTitle：无<title></title>降低 SEO 和书签可用性 -
Web:HtmlElementShouldNotBeUsed：禁用过时标签如<font></font>、<center></center> -
Web:HtmlInlineScript：检测内联<script></script>，利于 CSP 策略落地
慎用规则：Web:HtmlDuplicateId（跨文件 ID 冲突无法静态判定）、Web:HtmlPageShouldHaveMetaCharset（UTF-8 已成事实标准，且 BOM 或 HTTP header 可覆盖）。
所有规则激活后，务必在真实项目上跑一次完整扫描，检查是否出现大量误报——若某规则在 80% 的 HTML 文件里都报错，大概率是项目用了前端框架（如 Vue/React）导致静态分析失真，这时应把它从 Profile 中停用，或改用专用工具（如 axe-core）补充检测。
CI 流水线里怎么稳定触发 HTML 扫描？
很多人在 Jenkins/GitLab CI 里用 sonar-scanner 命令扫完发现 HTML 依旧没数据，问题往往出在环境隔离或路径解析上。
- 确保 CI 构建工作目录就是项目根目录（
sonar-project.properties所在位置），否则sonar.sources路径失效 - Docker 镜像里若用
sonarsource/sonar-scanner-cli，注意其默认WORKDIR是/home/sonar/scanner，需cd到项目路径再执行sonar-scanner - 避免在
sonar-scanner命令里用-Dsonar.sources=...覆盖sonar-project.properties，二者冲突时后者优先级更高 - 加一条调试命令：
ls -R | grep "\.html$"，确认 HTML 文件确实存在于扫描路径下
最后提醒：HTML 健康度不能只靠 SonarQube。它的强项是结构合规性，但无法判断语义是否恰当（如用 <div role="button"> 替代 <code><button></button>）、无法验证 ARIA 属性实际效果、也无法模拟用户交互流。真正闭环的 HTML 质量，得靠 SonarQube + axe-cli + Lighthouse CI 三者分工——前者管“写得对不对”，后两者管“用起来好不好”。
