摘要：
在自動化測試中，“測試全過但覆蓋率為 0%”或“SonarQube 與本地工具數據打架”是困擾開發者的典型難題 。作為 SonarQube 官方授權合作夥伴，龍智通過本文深度拆解 SonarQube 代碼覆蓋率的四階段管道 。我們將帶您精准定位 0% 覆蓋率的 7 大根因，並揭示 Python、Java 等語言在不同工具間產生數據偏差的底層邏輯 。通過構建確定性的驗證層，助力企業在 AI 提效的同時，守住代碼品質與安全的底線 。
這是一個常見的開發者場景：所有測試都通過了，但 SonarQube 顯示 0.0% 的代碼覆蓋率。或者覆蓋率確實出現了，但比 pytest 或 JaCoCo 在相同代碼上報告的數字低了 20 個百分點，而掃描器日誌也沒有解釋原因。
問題幾乎從不出在 SonarQube 本身。覆蓋率報告是一個四階段的管道，大多數故障發生在測試框架、覆蓋率工具、掃描器和儀錶盤之間的交接點。一旦你清楚地看到這個管道，診斷覆蓋率故障只需幾分鐘。
覆蓋率管道
TL;DR 概述
SonarQube 代碼覆蓋率衡量的是代碼庫中有多少代碼被自動化測試執行到了；它本身不生成覆蓋率數據。它導入由 JaCoCo、coverage.py、Istanbul 或你所用語言的等效工具生成的報告。管道隨後經歷四個階段，大多數故障發生在這些階段之間的交接點。
0% 覆蓋率幾乎總是可以追溯到以下七個原因之一：自動分析模式、報告檔缺失、格式錯誤、掃描器屬性名錯誤（已廢棄的屬性名會靜默失敗）、路徑錯誤、掃描器在測試之前運行，或報告中的檔路徑與專案佈局不匹配。
當工具之間的數字不一致時，原因通常是以下三種之一：對”可覆蓋行”的定義不同（Python 的 def 和 import、JaCoCo 的右花括弧）、檔範圍不同（你的覆蓋率工具只報告測試加載的檔；SonarQube 會看到每個檔），或 SonarQube 將行覆蓋率與分支覆蓋率合併為單一指標，而其他工具分開報告。
僅憑覆蓋率百分比會遺漏那些執行了代碼但未驗證結果的測試。SonarQube 規則會標記沒有斷言的測試（java:S2699）、斷言被困在 pytest.raises 塊中永遠無法執行的情況（python:S5915），以及空的測試類（java:S2187）。
覆蓋率管道
SonarQube 不生成代碼覆蓋率數據。它導入由第三方工具生成的報告。管道的工作方式如下：
- 你的測試框架（JUnit、pytest、Jest）運行你的測試。
- 覆蓋率工具（JaCoCo、coverage.py、Istanbul/c8）對你的代碼進行插樁，並記錄在這些測試期間執行了哪些行和分支。
- 覆蓋率工具將報告檔以特定格式（JaCoCo XML、Cobertura XML、LCOV）寫入磁片。
- sonar-scanner 通過配置的分析屬性讀取該報告檔，並將數據上傳到 SonarQube。
報告檔是交接產物。它位於你的構建工具鏈和 SonarQube 掃描器之間，也是大多數故障發生的地方，例如格式錯誤、路徑錯誤或檔完全缺失。
在實踐中，階段 1 和階段 2 通常合併為一條命令。JaCoCo 掛鉤到 Maven 的 test 階段。Jest 內置了 Istanbul。go test -coverprofile 將兩者合二為一。這種概念上的分離對於故障排查很重要，因為測試可能通過而覆蓋率工具未能生成報告，但你不需要運行兩條獨立的命令。
需要提前瞭解的一個限制是：覆蓋率要求使用基於 CI 的分析，即由你自己運行 sonar-scanner。SonarQube Cloud 的自動分析模式不支持覆蓋率導入。
每種編程語言都有自己的覆蓋率工具、報告格式和掃描器屬性：
| 語言 | 測試框架 | 覆蓋率工具 | 報告格式 | 掃描器屬性 |
|---|---|---|---|---|
Java (Maven) | JUnit 5 | JaCoCo (Maven plugin) | JaCoCo XML | sonar.coverage.jacoco.xmlReportPaths |
Java (Gradle) | JUnit 5 | JaCoCo (Gradle plugin) | JaCoCo XML | sonar.coverage.jacoco.xmlReportPaths |
JavaScript/TypeScript | Jest / Vitest | Istanbul / c8 | LCOV | sonar.javascript.lcov.reportPaths |
Python | pytest | coverage.py | Cobertura XML | sonar.python.coverage.reportPaths |
C# (.NET) | xUnit / NUnit | Dotnet-coverage / coverlet | VS Coverage XML / OpenCover XML | sonar.cs.vscoveragexml.reportsPaths or sonar.cs.opencover.reportsPaths |
Go | go test | Native (-coverprofile) | Go coverage format | sonar.go.coverage.reportPaths |
當覆蓋率顯示為 0%
管道有四個過渡點，任何一個過渡點的故障都會產生相同的症狀：儀錶盤上顯示 0% 覆蓋率。按順序逐一檢查以下專案，因為大多數問題在前四項中就能發現。
1. 你的分析模式是否支持覆蓋率？
自動分析不會導入覆蓋率報告。在 SonarQube Cloud 中檢查專案的 Administration > Analysis Method。如果顯示”Automatic”，請切換到基於 CI 的分析。無論怎麼配置屬性都無法解決這個問題。
2. 報告檔是否存在？
在 sonar-scanner 運行之前，你的構建必須生成覆蓋率報告。測試步驟完成後，驗證檔是否在你預期的位置：
| 語言 | 覆蓋率報告路徑 | 命令 |
|---|---|---|
Java (Maven) | target/site/jacoco/jacoco.xml | mvn verify（需配置 JaCoCo 插件） |
Java (Gradle) | build/reports/jacoco/test/jacocoTestReport.xml | ./gradlew test jacocoTestReport |
JavaScript/TypeScript | coverage/lcov.info | npx jest –coverage 或 npx vitest –coverage |
Python | coverage.xml | coverage run -m pytest && coverage xml |
C# (.NET) | coverage.xml | dotnet-coverage collect “dotnet test” -f xml -o coverage.xml |
Go | coverage.out | go test -coverprofile=coverage.out ./… |
如果構建步驟後檔不存在，問題出在你的構建配置，而不是 SonarQube。
3. 報告格式是否正確？
每種編程語言需要特定的格式。使用錯誤的格式會導致掃描器靜默忽略報告。你在正常輸出中不會看到錯誤或警告。
JaCoCo 必須生成 XML，而不是二進位 .exec 檔。舊的 sonar.jacoco.reportPaths 屬性（接受二進位格式）已被廢棄。Python 的 coverage.py 必須輸出 Cobertura XML（coverage xml），而不是 .coverage 二進位檔或 HTML 報告。JavaScript 覆蓋率必須是 LCOV，而不是 JSON 或 Clover 格式。
打開報告檔。XML 以 <?xml 開頭。LCOV 以 TN: 或 SF: 開頭。如果你看到的是二進位數據或 HTML 標籤，說明格式不對。
4. 掃描器屬性是否指向正確的檔？
掃描器需要一個屬性來告訴它在哪里找到報告。路徑是相對於 sonar-scanner 運行的目錄（通常是專案根目錄）的。報告在 build/coverage/lcov.info 而屬性設置為 coverage/lcov.info 就找不到。
檢查你的 sonar-project.properties 檔或 -D 參數：
# Java
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
# JavaScript / TypeScript
sonar.javascript.lcov.reportPaths=coverage/lcov.info
# Python
sonar.python.coverage.reportPaths=coverage.xml
5. 掃描器是否在覆蓋率報告生成之後運行？
一個常見的 CI 錯誤是 sonar-scanner 步驟在測試完成之前啟動，或者在一個不等待測試步驟的並行作業中運行。掃描器步驟必須在你的管道中明確依賴於測試步驟。
6. 報告中的檔路徑是否與專案結構匹配？
覆蓋率報告內部的路徑必須與 sonar-scanner 看到你原始檔案的方式一致。三種常見的路徑不匹配情況：
- CI 中的 Python：在 .coveragerc 或 pyproject.toml 中設置 relative_files = True。否則，coverage.py 會寫入絕對容器路徑（/home/runner/work/my-project/…），SonarQube 無法將其解析到你的源代碼樹，從而產生無錯誤的靜默 0% 覆蓋率。
- Monorepo：如果掃描器從倉庫根目錄運行，而覆蓋率報告引用的是相對於子目錄的檔路徑，路徑就會不匹配。
- 多模組 Maven：聚合的 JaCoCo 報告可能使用模組相對路徑。使用 JaCoCo 的 report-aggregate 目標並正確配置源代碼集。
7. 屬性名稱是否正確且為最新版本？
已廢棄或拼寫錯誤的屬性名會靜默導致 0% 覆蓋率。以下是容易出錯的屬性名：
| 已弃用（静默忽略） | 當前使用 |
|---|---|
sonar.jacoco.reportPaths | sonar.coverage.jacoco.xmlReportPaths |
sonar.typescript.lcov.reportPaths | sonar.javascript.lcov.reportPaths |
sonar.python.coverage.reportPath | sonar.python.coverage.reportPaths |
沒有警告，沒有錯誤消息；掃描器就是找不到覆蓋率數據。任何拼寫錯誤的屬性名都會以同樣的方式失敗。複製你的屬性名並與測試覆蓋率參數參考文檔進行核對。
檢查掃描器日誌
如果以上所有檢查都正確，請使用 -X 標誌運行掃描器以獲取調試輸出。搜索：
- Sensor JaCoCo XML Report Importer (Java) 以確認它找到了報告
- 關鍵字 coverage 以查看有多少檔導入了覆蓋率。如果日誌顯示 0，說明報告未找到或無法解析
- WARN 以查找未解析的檔路徑或缺失的報告
0% 覆蓋率？
|-- 使用自動分析？ -> 切換到基於 CI 的分析
|-- 報告檔存在？ -> 檢查構建配置
|-- 報告格式正確？ -> 使用 XML/LCOV，而非二進位
|-- 掃描器屬性正確？ -> 檢查名稱 + 路徑
|-- 掃描器在測試之後運行？ -> 修復 CI 步驟順序
|-- 檔路徑匹配？ -> 檢查 relative_files、monorepo 路徑
|-- 屬性名稱是最新版？ -> 檢查是否使用了廢棄名稱
|-- 仍然是 0%？ -> 使用 -X 運行掃描器，搜索 "coverage"
為什麼你的數字不一致
你修復了 0% 問題，覆蓋率出現在儀錶盤上；但 coverage.py 顯示 57%，而 SonarQube 顯示 38%。或者 JaCoCo 顯示 44%，SonarQube 顯示 42%。工具沒有問題，它們只是在計算不同的東西。
這是因為在 Python 中，def 是一條在類加載時執行的可執行語句，將函數對象綁定到一個名稱。當任何測試導入該模組時，每一行 def 都會執行，即使測試從未調用過該方法。coverage.py 將這些 def 行計入可覆蓋和已覆蓋的行，對 import 和 class 行也是如此。SonarQube 不將它們中的任何一個視為可執行的，因為它們不是邏輯語句。
五個 def 行、一個 import 和一個 class 聲明虛增了 coverage.py 的分子（全部七個都被”覆蓋”），卻沒有增加任何實際的覆蓋率信號。一個在 pytest 輸出中看到 57%、在儀錶盤上看到 38% 的開發者會認為 SonarQube 出錯了。SonarQube 衡量的是你的邏輯在測試期間有多少比例被執行了，而 import 時執行的 def 行並不能告訴你方法的主體是否被測試過。
同樣的原理在其他語言中也以較小的規模存在。在 Java 中，JaCoCo 在位元組碼層面操作，編譯器將返回位元組碼映射到方法的右花括弧。SonarQube 不將右花括弧計為可執行語句。對於一個簡單的 add() 方法：
public int add(int a, int b) {
lastResult = a + b; // 兩個工具：可覆蓋，已覆蓋
return lastResult; // 兩個工具：可覆蓋，已覆蓋
} // JaCoCo：可覆蓋 | SonarQube：不計入
同樣的模式重複出現在 divide()、classify() 和 getLastResult() 中，每個方法向 JaCoCo 的計數貢獻一個或兩個右花括弧，而 SonarQube 會忽略它們。在整個類中，JaCoCo 計算出 18 個可覆蓋行（包括 6 個花括弧），而 SonarQube 計算出 12 個。差距：JaCoCo 顯示 44.4%，SonarQube 顯示 41.7%。差距只有約 3%，因為計數差異僅限於花括弧。
| 語言 | 工具 | 工具報告 | SonarQube 報告 | 差異 | 主要原因 |
|---|---|---|---|---|---|
Python | coverage.py | 56.5% | 37.5% | ~19 pts | import、def、class 语句行被计入分母 |
JavaScript | Istanbul | 54.5% | 50.0% | ~4.5 pts | 類聲明、方法簽名行未覆蓋 |
Java | JaCoCo | 44.4% | 41.7% | ~3 pts | 右大括号 } 被计入可覆盖代码行 |
兩個根本原因可以解釋所有差異：
- 不同的分母。每個工具對”可覆蓋行”的定義不同。SonarQube 只計算可執行語句。coverage.py 包括 import、類聲明和函數定義。JaCoCo 包括右花括弧，Istanbul 包括類聲明和方法簽名。
- 不同的檔範圍。覆蓋率工具只報告測試期間加載的檔，但 SonarQube 包括所有專案檔。在分析的一個開源 Java 專案中，示例組件（143 行，0% 覆蓋率）將整體數字拉低到 53.2%，即使 IT 模組的覆蓋率達到了 76.7%。未經測試的工具代碼、生成的檔或沒有測試的模組在 SonarQube 中顯示為 0%，但在你的覆蓋率工具報告中根本不會出現。SonarQube 向你展示的是全貌，雖然有時不那麼好看。如果這些檔確實不應計入（生成的代碼、供應商依賴），可以通過 sonar.exclusions 排除它們。但你的覆蓋率工具默默忽略的未經測試的應用代碼是值得瞭解的。
- 第三個因素加劇了這兩者的影響：SonarQube 將行覆蓋率和分支覆蓋率合併為一個單一指標。
Coverage = (CT + CF + LC) / (2*B + EL)
CT 和 CF 是被評估為真和假的條件，LC 是已覆蓋的行，B 是總條件數，EL 是可執行行。每個分支計為兩倍，因為它有兩個結果。以實際專案數據為例，計算結果為 5,989 / 11,256 = 53.2%，與儀錶盤完全一致。JaCoCo 將行覆蓋率和分支覆蓋率作為單獨的數字報告，因此當你有很多未經測試的分支時，SonarQube 的合併指標會比 JaCoCo 僅計算行覆蓋率的數字更低。
在小型、測試充分的專案中，工具之間的差距只有幾個百分點。在包含未經測試的模組或生成代碼的大型專案中，差距可能更加顯著。
超越百分比：當代碼被覆蓋但未被測試
覆蓋率告訴你哪些行在測試期間被執行了，但沒有告訴你測試是否真正驗證了任何東西。一個調用了方法但沒有斷言結果的測試會為該方法產生完整的行覆蓋率，但不會捕獲任何 bug。SonarQube 通過分析測試品質（而不僅僅是測試執行）的規則來檢測這些缺口。
沒有斷言的測試 (java:S2699)
最常見的測試品質問題。一個執行了代碼但沒有斷言的測試提供了行覆蓋率，卻沒有驗證行為：
@Test
void testAddNoAssertion() { // Noncompliant: S2699
Calculator calc = new Calculator();
calc.add(2, 3);
// 行覆蓋率：add() 的 100%。捕獲的 bug：零。
}
SonarQube 將此標記為 BLOCKER（阻斷級）。該規則能識別來自許多流行框架的斷言，包括 JUnit、AssertJ、Mockito 和 Hamcrest，因此它不會標記使用受支持的斷言庫的測試。
永遠不會執行的斷言 (python:S5915)
更隱蔽，手動更難發現。pytest.raises 塊中的斷言永遠不會運行，因為異常會先退出塊：
def test_divide_by_zero():
calc = Calculator()
with pytest.raises(ValueError):
calc.divide(1, 0)
assert calc.last_result is None # 死代碼 — 永遠不會執行
測試通過了。coverage.py 將 raise 行標記為已覆蓋，但最後一行的斷言是死代碼。將其移出 with 塊即可修復。SonarQube 將此標記為高影響。
空的測試類 (java:S2187)
一個名為 CalculatorEdgeCaseTest 但沒有任何測試方法的類會出現在測試報告中，佔據測試目錄的空間，並讓閱讀專案的人以為邊緣情況已被覆蓋。SonarQube 將沒有測試方法的測試類標記為 BLOCKER，適用於 JUnit 3/4/5、TestNG 和其他受支持的框架。
這些規則能捕獲覆蓋率百分比完全遺漏的問題。AI 編程智能體經常生成這類具有高行覆蓋率但零有意義斷言的測試。
結語：構建透明且確定性的代碼品質度量體系
SonarQube 中的代碼覆蓋率報告是一個管道，而不是一個按鈕。當數字看起來不對時，問題不是”SonarQube 壞了嗎？”，而是”管道中哪里斷了鏈？”
有關特定語言的設置說明，請聯繫創實資訊！
高质量的代码覆盖不是“凑出来的”，而是“管出来的” 。
创实信息依托深厚的 DevSecOps 落地经验，为您提供：
- 排障与配置优化：解决 CI/CD 流程中覆盖率不显示或路径错位等技术瓶颈 。
- AI 时代治理方案：结合 Sonar 最新 AC/DC 框架，识别无断言测试等“质量假象”，提升测试效能 。
- 版本升级与试用：申请 SonarQube 2026.1 LTA 最新版试用，体验针对 Python、Java 的突破性分析速度 。
- 全周期技术支持：提供本地化架构规划、部署实施及专业培训服务 。
