4. SonarQube 扫描器：SonarScanner 的安装与配置（CLI、Maven、Gradle、Jenkins 插件）

SonarScanner 是 SonarQube 生态中的核心执行组件，负责对源代码进行静态分析并将结果上报至 SonarQube 服务器。根据项目构建工具和 CI 环境的不同，SonarScanner 提供了多种集成方式。本章将系统讲解 CLI 独立扫描器、Maven 与 Gradle 插件、以及 Jenkins 插件的安装与配置方法，帮助你在不同技术栈中快速建立代码质量扫描能力。

前置条件：在安装任何扫描器之前，请确保 SonarQube 服务器已正常运行，并且你已获取到服务器地址（例如 http://sonarqube.example.com:9000）以及有效的认证 。
SonarScanner 集成方式架构图 SonarQube Server CLI Scanner Maven Plugin Gradle Plugin Jenkins Plugin 所有扫描器均通过 HTTP(S) 协议将分析结果上报至 SonarQube Server，支持 认证 项目源代码（Java / JS / Python / C# / Go ...）

4.1 SonarScanner CLI 安装与配置

CLI 扫描器是最基础的独立运行方式，适用于非 Maven/Gradle 项目、脚本化扫描或快速验证场景。

4.1.1 下载与安装

  1. 访问 SonarQube 官方下载页面，获取与 SonarQube 服务器版本匹配的 SonarScanner CLI 压缩包。
  2. 解压至目标目录，例如 /opt/sonar-scanner 或 C:\sonar-scanner。
  3. 将 bin 目录添加到系统 PATH 环境变量中。
# Linux / macOS 示例
unzip sonar-scanner-cli-5.0.1.3006-linux.zip -d /opt/
export PATH=$PATH:/opt/sonar-scanner-5.0.1.3006-linux/bin

# 验证安装
sonar-scanner --version

4.1.2 全局配置文件

编辑 conf/sonar-scanner.properties 文件，配置服务器连接信息：

# 服务器地址
sonar.host.url=http://localhost:9000

# 认证 （推荐）或用户名/密码
sonar.login=sqa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 可选：配置 JDK 路径（如果系统默认 JDK 版本不兼容）
# sonar.java.home=/usr/lib/jvm/java-11-openjdk

4.1.3 项目级配置

在项目根目录创建 sonar-project.properties 文件：

# 项目唯一标识
sonar.projectKey=com.example:my-project
sonar.projectName=My Project
sonar.projectVersion=1.0.0

# 源代码目录（相对于项目根目录）
sonar.sources=src

# 编译后的字节码目录（Java 项目必需）
sonar.java.binaries=target/classes

# 语言
sonar.language=java

# 编码
sonar.sourceEncoding=UTF-8

4.1.4 执行扫描

cd /path/to/your/project
sonar-scanner
最佳实践：将 sonar.login 和 sonar.password 通过环境变量或 CI 密钥管理传递，避免硬编码在配置文件中。

4.2 Maven 插件配置

对于 Maven 项目，SonarScanner 以插件形式集成，无需额外下载 CLI，配置简洁且与构建生命周期无缝衔接。

4.2.1 在 pom.xml 中声明插件

<build>
  <plugins>
    <plugin>
      <groupId>org.sonarsource.scanner.maven</groupId>
      <artifactId>sonar-maven-plugin</artifactId>
      <version>3.11.0.3922</version>
    </plugin>
  </plugins>
</build>

4.2.2 配置服务器连接（settings.xml 或命令行）

方式一：在 ~/.m2/settings.xml 中配置全局服务器信息：

<settings>
  <profiles>
    <profile>
      <id>sonar</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <sonar.host.url>http://localhost:9000</sonar.host.url>
        <sonar.login>sqa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</sonar.login>
      </properties>
    </profile>
  </profiles>
</settings>

方式二：直接在命令行传递参数（适合 CI 环境）：

mvn clean verify sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=sqa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4.2.3 常用参数说明

参数 说明 示例值
sonar.projectKey 项目唯一标识 com.example:my-app
sonar.projectName 项目显示名称 My Application
sonar.branch.name 分支名称（需 Developer Edition 及以上） feature/login
sonar.coverage.jacoco.xmlReportPaths JaCoCo 覆盖率报告路径 target/site/jacoco/jacoco.xml
提示：Maven 插件会自动从 pom.xml 中读取 groupId:artifactId:version 作为默认的 sonar.projectKey，通常无需额外指定。

4.3 Gradle 插件配置

Gradle 项目通过 org.sonarqube 插件集成 SonarScanner，配置方式与 Maven 类似，但更贴合 Gradle 的 DSL 风格。

4.3.1 应用插件

在 build.gradle 中：

plugins {
  id "org.sonarqube" version "4.4.1.3373"
}

或使用旧版 buildscript 方式：

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "org.sonarsource.scanner.gradle:sonarqube-gradle-plugin:4.4.1.3373"
  }
}

apply plugin: "org.sonarqube"

4.3.2 配置 SonarQube 属性

sonarqube {
  properties {
    property "sonar.host.url", "http://localhost:9000"
    property "sonar.login", "sqa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    property "sonar.projectKey", "com.example:gradle-app"
    property "sonar.projectName", "Gradle Application"
    property "sonar.sourceEncoding", "UTF-8"
  }
}

4.3.3 执行扫描

# 先执行编译和测试，再运行 SonarQube 分析
./gradlew clean test sonarqube

# 或直接指定参数覆盖
./gradlew sonarqube \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=sqa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
注意：Gradle 插件默认不会自动编译项目。请确保在执行 sonarqube 任务之前，已经运行了 compileJava 和 test 等任务，否则分析可能因缺少字节码而失败。

4.4 Jenkins 插件配置

Jenkins 作为最流行的 CI/CD 引擎，通过 SonarQube Scanner for Jenkins 插件实现与 SonarQube 的深度集成，支持 Pipeline 和 Freestyle 项目。

4.4.1 安装插件

  1. 进入 Jenkins → 系统管理 → 插件管理 → 可选插件。
  2. 搜索 SonarQube Scanner 并安装。
  3. 重启 Jenkins 使插件生效。

4.4.2 配置 SonarQube 服务器

  1. 进入 Jenkins → 系统管理 → 系统配置。
  2. 找到 SonarQube servers 区域，点击 Add SonarQube。
  3. 填写以下信息：
字段 说明 示例值
Name 服务器标识名称 SonarQube-Prod
Server URL SonarQube 服务器地址 http://sonarqube.example.com:9000
Server authentication 在 Jenkins 凭据中创建的 Secret Text 类型 选择已配置的凭据

4.4.3 配置 SonarScanner 工具

  1. 进入 Jenkins → 系统管理 → 全局工具配置。
  2. 找到 SonarQube Scanner 区域，点击 Add SonarQube Scanner。
  3. 选择 Install automatically，并选择版本（建议与服务器版本匹配）。

4.4.4 Pipeline 集成示例

pipeline {
  agent any

  tools {
    // 引用全局工具配置中定义的 JDK 和 Maven
    jdk 'JDK-11'
    maven 'Maven-3.9'
  }

  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }

    stage('Build & Test') {
      steps {
        sh 'mvn clean verify'
      }
    }

    stage('SonarQube Analysis') {
      steps {
        // 使用配置的 SonarQube 服务器和扫描器
        withSonarQubeEnv('SonarQube-Prod') {
          sh 'mvn sonar:sonar'
        }
      }
    }

    stage('Quality Gate Check') {
      steps {
        // 等待 SonarQube 分析完成并检查质量阈
        timeout(time: 5, unit: 'MINUTES') {
          waitForQualityGate abortPipeline: true
        }
      }
    }
  }
}

4.4.5 Freestyle 项目配置

  1. 在项目配置中，添加构建步骤 Invoke Standalone SonarQube Scanner。
  2. 在 Analysis properties 中填写项目属性：
sonar.projectKey=com.example:freestyle-app
sonar.projectName=Freestyle Application
sonar.projectVersion=1.0.0
sonar.sources=src
sonar.java.binaries=target/classes
sonar.sourceEncoding=UTF-8
关键点：Jenkins Pipeline 中的 withSonarQubeEnv 会自动注入 sonar.host.url 和 sonar.login 环境变量，无需在命令行中重复指定。waitForQualityGate 步骤可实现质量阈自动门禁，阻断不合格代码进入后续阶段。

4.5 四种集成方式对比

集成方式 适用场景 依赖 配置复杂度 推荐度
CLI Scanner 非 Maven/Gradle 项目、脚本化扫描、快速验证 需单独下载安装 中等 ⭐⭐⭐
Maven Plugin Maven 项目、标准 Java 构建 仅需 pom.xml 声明 低 ⭐⭐⭐⭐⭐
Gradle Plugin Gradle 项目、Android 项目 仅需 build.gradle 声明 低 ⭐⭐⭐⭐⭐
Jenkins Plugin CI/CD 流水线、多分支、质量门禁 需安装 Jenkins 插件 中等 ⭐⭐⭐⭐
四种扫描器配置流程对比 CLI Scanner 下载 → 解压 → 配置 → sonar-project.properties → sonar-scanner 命令 Maven Plugin pom.xml 声明插件 → settings.xml 配服务器 → mvn sonar:sonar Gradle Plugin build.gradle 应用插件 → sonarqube 配置块 → gradle sonarqube Jenkins Plugin 安装插件 → 配服务器 → 配扫描器工具 → Pipeline / Freestyle 所有方式最终均通过 HTTP(S) 将分析结果上报至 SonarQube Server 选择原则：项目构建工具优先匹配插件，非标准项目使用 CLI，CI 环境推荐 Jenkins 集成

4.6 常见问题与排查

问题现象 可能原因 解决方案
扫描失败：Not authorized 无效或未配置 检查 sonar.login 是否正确，或在 SonarQube 中重新生成
扫描成功但无结果 项目 Key 与已有项目冲突 使用唯一的 sonar.projectKey，或删除旧项目后重试
Maven 扫描报 java.lang.OutOfMemoryError JVM 堆内存不足 设置 MAVEN_OPTS=-Xmx2g 或 SONAR_SCANNER_OPTS=-Xmx2g
Jenkins Pipeline 中 waitForQualityGate 超时 SonarQube Webhook 未配置 在 SonarQube 管理界面配置 Jenkins Webhook URL
版本兼容性：SonarScanner 版本必须与 SonarQube 服务器版本兼容。建议使用 SonarQube 官方兼容性矩阵进行核对，避免因版本不匹配导致分析失败或功能缺失。

通过本章的学习，你已经掌握了四种主流 SonarScanner 集成方式的安装与配置方法。在实际项目中，应根据团队技术栈和 CI/CD 基础设施选择最合适的方案，并确保扫描器版本与 SonarQube 服务器保持一致，从而为后续的质量门禁与缺陷闭环管理打下坚实基础。

← 上一章 📖 返回目录 下一章 →