SonarScanner CLI 使用

1. Scanner CLI 做了什么#

Scanner CLI 会读取项目配置，分析本地源码，然后把分析报告发送到 SonarQube Server。

它不会直接决定 Quality Gate 是否通过。Quality Gate 的计算在 Server 侧完成。Scanner 可以通过参数等待门禁结果，并让 CI 步骤失败。

2. 配置文件位置#

通用配置文件名是：

1
sonar-project.properties

通常放在项目根目录：

1
my-app/
2
├─ src/
3
├─ tests/
4
└─ sonar-project.properties

执行扫描时，在项目根目录运行：

1
sonar-scanner

3. 最小配置#

最小配置示例：

1
sonar.projectKey=my-app
2
sonar.projectName=my-app
3
sonar.sources=src
4
sonar.host.url=http://sonarqube.example.com:9000

认证 token 不建议写进文件，而是通过环境变量传入：

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

官方文档中 sonar.token 已经替代旧的 sonar.login 和 sonar.password。

4. 常用参数说明#

sonar.projectKey：

• 项目唯一标识。
• 必须稳定。
• 应和 SonarQube Server 中项目 key 对应。

sonar.projectName：

• 页面展示名称。
• 可以比 project key 更适合人读。

sonar.sources：

• 主源码目录。
• 可以写相对路径，例如 src。
• 多个目录用逗号分隔。

sonar.tests：

• 测试代码目录。
• 如果不设置，测试代码不会按测试范围识别。

sonar.host.url：

• SonarQube Server 地址。
• CI 主机必须能访问这个地址。

sonar.token：

• Scanner 认证用 token。
• 推荐用 SONAR_TOKEN 环境变量传入。

sonar.qualitygate.wait：

• 是否等待 Quality Gate 结果。
• 设置为 true 后，门禁失败会让扫描步骤失败。

5. 参数优先级#

常见优先级从低到高可以理解为：

1
全局 UI 配置
2
项目 UI 配置
3
scanner 配置文件
4
命令行 -D 参数

命令行参数适合 CI 临时覆盖，项目长期配置更适合放在 UI 或配置文件里。

1. 普通项目#

1
sonar.projectKey=my-app
2
sonar.projectName=my-app
3
sonar.sources=src
4
sonar.tests=tests
5
sonar.host.url=http://sonarqube.example.com:9000
6
sonar.sourceEncoding=UTF-8

运行：

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

2. 等待 Quality Gate#

1
export SONAR_TOKEN="your-project-token"
2
sonar-scanner -Dsonar.qualitygate.wait=true

这个写法适合 CI/CD。门禁失败时，扫描步骤会失败，流水线可以停止。

3. 命令行覆盖配置#

1
sonar-scanner \
2
  -Dsonar.projectKey=my-app \
3
  -Dsonar.sources=src \
4
  -Dsonar.host.url=http://sonarqube.example.com:9000 \
5
  -Dsonar.qualitygate.wait=true

命令行覆盖适合流水线动态传参，但不要把 token 明文写在命令历史或日志里。

1. 把 token 写进仓库#

不要在 sonar-project.properties 中写：

1
sonar.token=真实token

更推荐：

1
export SONAR_TOKEN="your-project-token"

2. projectKey 和服务端项目不一致#

如果 sonar.projectKey 写错，扫描结果可能进入错误项目，或者提示项目不存在、无权限。

3. sources 指到错误目录#

sonar.sources=. 看起来省事，但可能把构建产物、依赖目录、临时文件也纳入扫描范围。更稳妥的是明确写源码目录。

4. 以为 scanner 会自动跑测试#

Scanner 负责代码分析，不等于自动执行单元测试。覆盖率报告通常要先由测试工具生成，再配置给 SonarQube 读取。

5. 在日志里暴露敏感信息#

开启 sonar.verbose=true 或打印环境变量时，注意不要把 token、数据库密码、代理密码暴露到 CI 日志里。