🧭 一、SonarQube 简介

SonarQube 是一个开源的持续代码质量管理平台，支持包括 PHP 在内的多种语言。
它可以帮助你检测：

  • 潜在的 Bug
  • 安全漏洞（Security Vulnerabilities）
  • 代码异味（Code Smells）
  • 测试覆盖率
  • 重复代码 等

⚙️ 二、环境准备

1️⃣ 系统要求

  • Java 17+（SonarQube Server 运行需要）
  • 数据库：PostgreSQL（推荐）、MySQL（老版本支持）
  • SonarScanner（代码扫描器）
  • SonarQube Server

🧩 三、安装步骤

1️⃣ 下载 SonarQube

前往官网：https://www.sonarsource.com/products/sonarqube/downloads/

选择版本：

  • Community Edition 免费版（支持 PHP）
  • Developer / Enterprise Edition 提供更高级的规则与安全检测

解压后进入：

cd sonarqube-<version>/bin

根据系统启动：

# Linux / Mac
./sonar.sh start
# Windows
StartSonar.bat

访问：

http://localhost:9000

默认账号：

admin / admin

🧰 四、安装 SonarScanner（扫描器）

SonarScanner 是将项目代码提交给 SonarQube Server 分析的工具。

安装方式：

macOS

brew install sonar-scanner

Ubuntu

sudo apt install sonar-scanner

Windows

从 SonarScanner 官方页面 下载解压，配置环境变量。

📂 五、项目配置（以 PHP 为例）

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

内容如下：

# 项目信息
sonar.projectKey=my-php-project
sonar.projectName=My PHP Project
sonar.projectVersion=1.0

# 源代码路径
sonar.sources=src

# PHP 语言设置
sonar.language=php

# PHP 版本（可选）
sonar.php.version=8.2

# 排除不需要扫描的目录
sonar.exclusions=vendor/**, tests/**

# 测试覆盖率报告（如果使用 PHPUnit）
sonar.php.coverage.reportPaths=build/logs/clover.xml

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

# 登录令牌（推荐使用 Token 而非密码）
sonar.login=<你的 SonarQube Token>

🧪 六、执行扫描

在项目根目录运行：

sonar-scanner

运行结果示例：

INFO: Analysis total time: 15.487 s
INFO: ANALYSIS SUCCESSFUL, you can browse http://localhost:9000/dashboard?id=my-php-project

浏览器打开 SonarQube 页面即可查看详细分析结果。

🧱 七、与 PHPUnit 集成（可选）

如果你有单元测试并希望统计覆盖率：

1️⃣ 安装 PHPUnit：

composer require --dev phpunit/phpunit

2️⃣ 生成测试覆盖率报告：

vendor/bin/phpunit --coverage-clover build/logs/clover.xml

3️⃣ 在 sonar-project.properties 中添加：

sonar.php.coverage.reportPaths=build/logs/clover.xml

🛠️ 八、CI/CD 集成（可选）

在 CI 工具（如 GitHub Actions、GitLab CI、Jenkins）中加入 Sonar 扫描步骤。

示例：GitHub Actions

.github/workflows/sonar.yml

name: SonarQube Scan

on:
  push:
    branches: [ "main" ]
  pull_request:

jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - name: Install dependencies
        run: composer install
      - name: Run tests
        run: vendor/bin/phpunit --coverage-clover build/logs/clover.xml
      - name: SonarQube Scan
        run: sonar-scanner
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: http://<your-sonarqube-server>

🧠 九、查看与分析结果

在 SonarQube Web 界面中查看：

  • Issues（问题）：安全漏洞、代码异味、Bug
  • Quality Gate（质量门槛）：是否通过预设标准
  • Coverage（测试覆盖率）
  • Duplications（重复代码）

🛡️ 十、常见问题

问题原因解决方案
“Failed to connect to server”SonarQube 未启动或 URL 配置错误检查 sonar.host.url
“Missing login”未配置 Token在 SonarQube 个人设置生成 Token 并填入
“No analysis was performed on any file”源代码路径错误检查 sonar.sources 配置
“Coverage not displayed”未正确生成 clover.xml使用 --coverage-clover 参数运行 PHPUnit

📘 十一、实用参考