類路徑本質：JVM尋找.class文件的路徑地圖
類路徑定義類加載器去哪裡查找用戶類（非JRE核心類、擴展類）。它由路徑條目組成，每個條目可以是：
- 目錄（包含包層級結構的根目錄）
- JAR/ZIP文件（內部包含包結構）
核心原則：文件系統目錄層次**必須鏡像**Java包層次。類com.example.Foo對應文件/path/to/root/com/example/Foo.class，類路徑條目為/path/to/root（目錄）或/path/to/lib.jar（JAR包含com/example/Foo.class）。
設置類路徑的兩種標準方式
方式一：命令行參數 -cp / -classpath（推薦，進程級隔離）
# 編譯
javac -d out -cp lib/dependency.jar src/com/example/Main.java
# 運行
java -cp out:lib/dependency.jar com.example.Main
# Windows用分號分隔
java -cp out;lib/dependency.jar com.example.Main
- 優勢：每個應用獨立類路徑，互不干擾，構建腳本/CI/CD友好。
-cp是-classpath簡寫，java/javac/javadoc/javap等均支持。
方式二：CLASSPATH環境變量（不推薦，全局污染）
# Linux/MacOS
export CLASSPATH=/home/user/lib/dependency.jar:./out
# Windows (CMD)
set CLASSPATH=C:\lib\dependency.jar;.\out
# Windows (PowerShell)
$env:CLASSPATH="C:\lib\dependency.jar;.\out"
- 劣勢：影響同一Shell/系統下所有Java進程，版本衝突極難排查，**嚴禁在生產/開發環境設置**。
- 若歷史腳本依賴，請在啟動腳本開頭
unset CLASSPATH或set CLASSPATH=清空。
JVM類搜索順序：雙親委派與類路徑位置
- Bootstrap ClassLoader：加載
$JAVA_HOME/jre/lib/rt.jar等核心類（java.*, javax.*）。
- Extension ClassLoader：加載
$JAVA_HOME/jre/lib/ext/*.jar（Java 9+模塊化後機制變更）。
- Application ClassLoader (系統類加載器)：加載類路徑（-cp/CLASSPATH）指定的所有路徑**，按**聲明順序**從左到右查找，找到即返回。
**順序決定一切**：java -cp a.jar:b.jar Main 中若a.jar和b.jar都含com.example.Foo，**永遠加載a.jar中的版本**。
路徑條目寫法規範
| 目標類型 | 路徑條目寫法 | 示例 |
|---|
| 目錄（非默認包類） | 包含頂層包目錄的父目錄** | 類com.example.Foo在/app/classes/com/example/Foo.class → 條目/app/classes |
| 目錄（默認包類） | 直接包含.class文件的目錄 | /app/classes (含Foo.class) |
| JAR/ZIP文件 | 文件完整路徑 | /app/lib/utils.jar |
| 當前目錄 | . (Linux/Mac) 或 . (Windows) | java -cp .:lib.jar Main |
**常見錯誤**：將com/example作為類路徑條目 → JVM尋找com/example/com/example/Foo.class → 找不到。條目必須指向包根目錄的父目錄。
四大隱性類路徑陷阱
| 陷阱 | 機制 | 後果 | 防範 |
|---|
當前工作目錄 . | JVM自動將.加入類路徑 | 無意加載項目根目錄下臨時.class文件 | 嚴格src/bin分離，不在工作目錄放代碼 |
| CLASSPATH環境變量 | 系統/用戶環境變量 | 全局污染，多項目版本衝突 | **刪除/清空**環境變量，構建工具傳遞-cp |
JRE擴展目錄 jre/lib/ext | Extension ClassLoader自動掃描 | 影響所有Java進程，服務器部署災難 | **禁止放入業務JAR**；覆蓋系統類用-Xbootclasspath/p |
JRE endorsed目錄 jre/lib/endorsed | Bootstrap ClassLoader優先加載 | 覆蓋核心API（如XML解析器），副作用不可控 | 運行時用-Xbootclasspath/p:jar路徑精準控制 |
實戰最佳實踐：從開發到生產
1. 開發階段：IDE + 構建工具雙重保障
- IDE：Eclipse/IntelliJ 管理 Module Dependencies、Source Folders、Output Folders，自動構建類路徑。
- Maven/Gradle：
mvn compile/test 自動構建含傳遞依賴的類路徑，**標準目錄結構** (src/main/java, src/test/java) 保證包目錄對齊。
- **原則**：IDE配置與構建工具配置**保持一致**，以構建工具為準（CI/CD以構建工具為準）。
2. 打包部署：Fat JAR / WAR / 模塊化
- Spring Boot Fat JAR：
java -cp app.jar com.example.Main 或 java -jar app.jar (MANIFEST.MF含Class-Path/Start-Class)。
- 傳統WAR：放入Servlet容器
WEB-INF/lib (類庫)、WEB-INF/classes (類文件)，容器自動構建WebAppClassLoader。
- 模塊化：
java --module-path mods -m com.example/com.example.Main。
3. 疑難排查工具箱
# 1. 觀察實際加載類的來源
java -verbose:class -cp ... Main 2>&1 | grep "com.example.Foo"
# 2. 打印系統類路徑
java -cp ... -XshowSettings:properties 2>&1 | grep classpath
# 3. 檢查JAR包內容
jar tf lib/suspicious.jar | grep Foo.class
# 4. 反編譯驗證版本
javap -c -cp target/classes com.example.Foo
# 5. 運行時動態查看
System.out.println(System.getProperty("java.class.path"));
// 或
ClassLoader cl = MyClass.class.getClassLoader();
URLClassLoader ucl = (URLClassLoader) cl;
Arrays.stream(ucl.getURLs()).forEach(System.out::println);
跨平台路徑分隔符速查表
| 平台 | 路徑分隔符 (文件內部) | 類路徑列表分隔符 | 示例 |
|---|
| Linux / MacOS / Unix | / | : (冒號) | java -cp /app/bin:/lib/a.jar Main |
| Windows | \ (或 / 兼容) | ; (分號) | java -cp C:\app\bin;C:\lib\a.jar Main |
**建議**：命令行腳本/構建文件統一使用正斜杠/作為路徑分隔符，**類路徑列表分隔符按平台區分**（: / ;），Maven/Gradle自動處理跨平台差異。
總結：類路徑管理十條鐵律
- 類必須屬於包，包名遵循倒置域名+全小寫完整單詞。
- 目錄層次嚴格鏡像包層次，
src/bin/out分離。
- 編譯**必須**
-d指定輸出目錄，-sourcepath指定源碼根目錄。
- 運行**必須**
-cp顯式指定類路徑，包含輸出目錄與所有依賴JAR。
- 主類參數用全限定名（
com.example.Main），非文件路徑。
- **刪除/清空** CLASSPATH 環境變量。
- **禁止**向
jre/lib/ext、jre/lib/endorsed 放業務 JAR。
- 類路徑條目指向包根目錄的父目錄，非包目錄本身。
- 排查問題：
pwd/cd確認工作目錄，ls/dir驗證文件存在，javac -verbose/java -verbose:class觀察加載路徑。
- 找不到錯誤時，**請同事幫忙看一眼**——拼寫錯誤、目錄層級錯位、分隔符錯誤、環境變量殘留，旁觀者秒發現。
