售前问题

在SonarQube里，项目权限这件事最容易被理解错的地方，不是按钮在哪里，而是“继承”到底指什么。按官方口径，项目创建时会先套用一套Permission Template，也就是模板默认权限；但模板套上去以后，项目和模板之间并不存在持续联动关系，后面你手工改项目权限、或者再去改模板，本来就不会自动互相跟着变。再加上SonarQube的项目权限本身又不是累加关系，所以很多人看到“模板明明给了权限，项目里却不对”，本质上往往是把“初始化套用”误当成了“持续继承”。

很多团队把SonarQube接进流水线以后，主干分析通常很快就能跑起来，但一到分支分析，问题就会集中在两处。一处是不确定分支到底怎么建出来，另一处是不知道分支结果和主干该按什么口径去比。按SonarSource当前官方文档，分支分析从Developer Edition起才提供，分支是在分析时传入sonar.branch.name后创建出来的；而分支和主干的对比，本质上又不是靠手工看两份报告，而是靠Reference branch也就是参考分支，配合New Code口径去做差异判断。把这两层先分清，后面配置和看结果都会顺很多。

很多人第一次用SonarQube看安全问题时，容易把普通Issues和Security Hotspots混在一起，结果一边找不到入口，一边又误以为安全热点也能像普通问题那样直接批量改状态。官方文档把这两类对象分得很清楚，Security Hotspots有独立页面和独立生命周期，查看和处理逻辑都不完全等同于普通Issues。

很多团队在用SonarQube时，真正容易混淆的不是有没有New Code，而是“新代码到底从哪一天开始算”和“项目、分支、全局到底谁说了算”。SonarQube官方把这套逻辑定义得很清楚，New Code可以按Previous version、Number of days、Specific analysis、Reference branch四种方式来定义，而且配置有全局、项目、分支三层覆盖关系，分支级优先于项目级，项目级优先于全局级。

在SonarQube里，所谓“规则集”对应的其实是Quality Profile，也就是按语言生效的一组启用规则。真正容易出问题的地方，通常不是不会点启用和禁用，而是项目绑错了Profile、子Profile继承了父Profile、改完以后没有重新分析，结果看起来像是“规则明明关了却还在触发”。官方文档也明确说明，问题是在分析时根据项目关联的Quality Profile被产生出来的。

SonarQube里覆盖率显示为0，很多时候不是测试根本没跑，而是覆盖率报告没有在扫描前生成、扫描器没找到文件、报告格式和参数名不匹配，或者报告里的路径和当前项目根目录对不上。官方文档写得很明确，SonarQube本身不会生成覆盖率报告，它只负责导入外部工具生成的报告，所以排查顺序一定要先看报告有没有生成，再看扫描器有没有正确读到。