SonarQube 常见扫描问题与排查

1. token 错误或权限不足#

常见现象：

• 扫描提示未认证。
• 提示没有执行分析权限。
• 本地能登录页面，但 CI 扫描失败。

排查点：

• token 是否复制完整。
• token 是否属于正确用户或项目。
• 用户是否有 Execute Analysis 权限。
• CI 变量名是否正确注入。

推荐写法：

1
export SONAR_TOKEN="your-project-token"
2
sonar-scanner

不要把 token 写进仓库里的 sonar-project.properties。

2. project key 不一致#

常见现象：

• 扫描成功，但页面上看不到结果。
• 结果出现在另一个项目里。
• 提示项目不存在或无权限。

排查点：

1
sonar.projectKey=my-app

它必须和 SonarQube Server 上项目 key 对应。Project Key 应该稳定，不要随意改。

3. 扫描不到文件#

常见现象：

• 扫描成功但没有问题。
• 页面显示代码行数很少。
• 某些目录完全没被分析。

排查点：

1
sonar.sources=src
2
sonar.tests=tests

确认这些路径相对的是扫描启动目录。CI 中常见问题是工作目录和本地不一致。

可以在 CI 中先打印：

1
pwd
2
ls -la
3
find . -maxdepth 2 -type d

4. 证书或代理问题#

常见现象：

• Scanner 无法连接 HTTPS SonarQube。
• 报证书不受信任。
• 公司代理环境下连接超时。

排查点：

• CI 主机能否 curl 到 SonarQube 地址。
• 证书链是否被 JDK 信任。
• 代理环境变量是否配置。
• SonarQube 的 Server Base URL 是否和实际访问地址一致。

优先确认网络连通：

1
curl -I https://sonarqube.example.com

5. 内存不足或 Scanner 运行慢#

常见现象：

• 扫描过程中 OOM。
• 大项目扫描时间很长。
• CI runner 资源不足。

排查方向：

• 缩小 sonar.sources，不要扫描依赖目录和构建产物。
• 检查是否误把 node_modules、dist、target 纳入扫描。
• 给 Scanner 增加 JVM 内存。

示例：

1
export SONAR_SCANNER_OPTS="-Xmx2g"
2
sonar-scanner

6. Quality Gate 没等到结果#

默认情况下，Scanner 上传报告后，Quality Gate 在 Server 端异步计算。

如果流水线要等待门禁：

1
sonar-scanner -Dsonar.qualitygate.wait=true

如果项目大或 Server 繁忙，可以增加等待时间：

1
sonar-scanner \
2
  -Dsonar.qualitygate.wait=true \
3
  -Dsonar.qualitygate.timeout=600

7. 覆盖率一直是 0#

SonarQube 不会自动跑测试，也不会凭空生成覆盖率。

排查点：

• 测试命令是否在扫描前执行。
• 覆盖率报告是否真的生成。
• 报告路径是否被正确配置。
• 使用的语言和覆盖率格式是否匹配。

这个问题通常不是 Quality Gate 本身的问题，而是覆盖率报告没有被导入。

Scanner 侧#

先看 CI 控制台输出。需要更多信息时：

1
sonar-scanner -X

注意：调试日志可能输出更多环境信息，不要把敏感 token 暴露到公开日志里。

Server 侧#

常见日志：

1
logs/web.log
2
logs/ce.log
3
logs/es.log
4
logs/sonar.log

其中：

• web.log：Web 服务和 API 问题。
• ce.log：后台计算任务问题，Quality Gate 计算也在这个链路里。
• es.log：搜索引擎组件问题。
• sonar.log：总入口日志。

容器或 Kubernetes 部署时，也要看容器日志和 Pod 事件。

1. 只看 Scanner 成功，不看 Server 后台任务#

Scanner 成功上传报告，不代表 Server 一定完成了计算。页面里的后台任务失败时，也可能导致结果不可用。

2. 在错误目录执行扫描#

sonar.sources=src 是相对扫描启动目录解析的。CI 中 pwd 不同，结果就可能完全不同。

3. 忽略 SCM 信息#

SonarQube 会利用 SCM 信息识别新代码和变更。如果 CI 只拉了浅克隆或缺少分支信息，可能影响新代码判断。

4. 把所有问题都归因于规则太严#

规则确实可能需要调整，但接入初期更常见的是路径、权限、token、覆盖率报告和 CI 工作目录问题。