Java Classpath 配置排錯實戰：大小寫敏感導致的類加載失敗

故障現場

開發者配置好 Classpath 環境變量，簡單測試類運行正常，但引入自定義 util 包的類編譯通過、運行卻拋出 NoClassDefFoundError。截圖顯示環境變量包含目標目錄，邏輯上應能讀取到類文件。

根因分析

核心問題：包名/類名大小寫不匹配。 Windows 文件系統不區分大小寫，但 Java 類加載器嚴格區分。開發者在代碼中 import util.Tool;，實際目錄結構卻是 Util/Tool.class（首字母大寫），導致類加載器在 Classpath 中找不到 util/Tool.class。

排查步驟復盤

1. 驗證基礎環境：編寫無依賴的 HelloWorld 正常運行 → JDK/基礎 Classpath 無誤
2. 定位差異點：僅引入自定義包時失敗 → 問題在自定義包路徑或命名
3. 對比導入語句與實際目錄：發現 import util.xxx 與目錄 Util/ 大小寫不一致

Classpath 進階補充知識

1. 多路徑分隔符

• Windows：分號 ;
• Linux/macOS：冒號 :

2. 優先級順序

類加載搜索順序：Bootstrap → Extension → Application(Classpath)。同名類按順序第一個被找到的生效，這也是「jar 包衝突」的根源。

3. 通配符用法（Java 6+）

java -cp "lib/*;." MainClass  // 自動加載 lib 目錄下所有 jar

注意：* 不會遞歸子目錄，且不包含當前目錄 .，需顯式添加。

4. 清單屬性 Class-Path

可執行 Jar 的 MANIFEST.MF 中聲明依賴：

Class-Path: lib/utils.jar lib/log4j.jar

路徑相對於 Jar 文件位置，避免環境變量污染。

最佳實踐建議

1. 嚴格遵循命名規範：包名全小寫、類名帕斯卡命名、文件名與類名完全一致
2. 拒絕手動配置環境變量：使用 Maven/Gradle 管理依賴，IDE 自動構建 Classpath
3. 善用診斷命令：java -verbose:class 觀察類加載來源，java -XshowSettings:properties 查看生效系統屬性

這個「低級錯誤」實則揭示了跨平台開發中文件系統大小寫敏感差異的經典坑點。養成規範命名習慣，配合構建工具托管依賴，能從根源消除此類故障。