Java NoClassDefFoundError 排查指南：單測通過但集成失效的經典案例

錯誤現場

java.lang.NoClassDefFoundError: com/sun/pdfview/PDFFile
    at com.gotop.common.PdfToJpgTest.setup(PdfToJpgTest.java:28)

現象：PDFRenderer-0.9.0.jar 已導入，單獨運行測試類通過，集成到項目中報錯。

核心區別：ClassNotFoundException vs NoClassDefFoundError

排查清單（按可能性排序）

1. 傳遞依賴缺失：PDFRenderer 依賴其他 JAR (如 jai_imageio, jbig2) 未打包。用 mvn dependency:tree 或 IDEA「Dependencies」面板檢查。
2. 類路徑衝突：項目中存在同包不同版本的類（如多個 PDF 库），類加載器載入了錯誤版本，導致靜態塊報錯。mvn dependency:analyze 定位。
3. 類加載器隔離：Web 容器、OSGi、插件系統中，測試類加載器能見到 JAR，但業務線程類加載器不可見。檢查 Thread.currentThread().getContextClassLoader()。
4. 靜態初始化異常：PDFFile 類的 static {} 塊拋出異常（如訪問本地圖形環境 Headless 模式未啟動）。添加 JVM 參數 -Djava.awt.headless=true。
5. JDK 版本不兼容：PDFRenderer-0.9.0 年代久遠，可能不支持 JDK 1.4+ 的某些特性，或需要舊版 rt.jar 類。建議遷移至維護中的 Apache PDFBox 或 iText。

快速定位技巧

// 在報錯前添加斷點或日誌，打印類加載器與類路徑
System.out.println(PdfToJpgTest.class.getClassLoader());
System.out.println(System.getProperty("java.class.path"));
// 或啟用 JVM 參數
-verbose:class -XX:+TraceClassLoading

最佳實踐

• 使用 Maven/Gradle 管理依賴，避免手動導入 JAR 導致傳遞依賴丟失。
• 單元測試與集成測試環境對齊（同一 Classpath、同一 JDK、同一容器）。
• 棄用停更 10 年+ 的庫，拥抱活躍社區替代品。