Java 類路徑 (Classpath) 深度解析：徹底搞懂 NoClassDefFoundError

前言

初學 Java 最常遇到的錯誤莫過於 `Exception in thread "main" java.lang.NoClassDefFoundError` 或 `Could not find or load main class`。本文從 JVM 類載入機制出發，系統講解 Classpath 的三種指定方式、包與目錄對應關係、JAR 檔案製作與執行，助你徹底根治類找不到問題。

JVM 類載入搜尋順序

1. 啟動類：`rt.jar`、`i18n.jar` 等核心類庫 (`$JAVA_HOME/jre/lib`)。
2. 擴展類：`$JAVA_HOME/jre/lib/ext` 目錄下所有 JAR。
3. 使用者類：開發者自定義類與第三方庫，**必須透過 Classpath 指定**。

指定使用者 Classpath 的三種方式 (優先級遞增)

1. 預設值：當前目錄 (`.`) — 未設定任何 Classpath 時生效。
2. 環境變數 `CLASSPATH` — 覆蓋預設值，一旦設定，**必須手動加入 `.` 才能載入當前目錄類**。
3. 啟動參數 `-cp` / `-classpath` — 最高優先級，覆蓋環境變數。
   範例：`java -cp .;lib/mysql.jar;lib/log4j.jar com.example.Main`

特殊情況：`java -jar app.jar` 會**忽略所有 Classpath**，僅從該 JAR 的 `MANIFEST.MF` `Class-Path` 屬性載入依賴。

實戰案例：HelloWorld 類找不到

// HelloWorld.java
package pkg;
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

目錄結構：

project/
├── src/
│   └── pkg/
│       └── HelloWorld.java
└── classes/  (編譯輸出目錄)

正確編譯與執行：

cd project/src
javac -d ../classes pkg/HelloWorld.java
cd ../classes
java pkg.HelloWorld          # 正確：完整類名 pkg.HelloWorld
# java pkg/HelloWorld       # 錯誤：視為類名 "pkg/HelloWorld"

包與目錄的強制對應規則

• 原始碼：`package pkg.sub;` → 檔案必須置於 `src/pkg/sub/` 目錄。
• 編譯輸出：`-d classes` 會自動建立 `classes/pkg/sub/HelloWorld.class`。
• 執行時 Classpath 指向 `classes` 根目錄，JVM 會自動在 `classes/pkg/sub/` 尋找類。
• `import pkg.sub.*;` 編譯時同樣從 Classpath 根目錄尋找 `pkg/sub/` 目錄。

JAR 檔案打包與執行

cd classes
jar -cvf myapp.jar pkg          # 打包 pkg 目錄
jar -cvfm myapp.jar manifest.txt pkg  # 指定 Manifest

`manifest.txt` 內容：

Manifest-Version: 1.0
Main-Class: pkg.HelloWorld
Class-Path: lib/dependency.jar  # 相對路徑

執行：`java -jar myapp.jar` (無需指定 Classpath)。

常見坑與避雷指南

現代化建議：拋棄手動 Classpath

• Maven / Gradle：依賴管理、自動構建 Classpath、生成 Fat JAR (`maven-shade-plugin` / `shadowJar`)。
• IDE 專案結構：標準 `src/main/java`、`src/test/java`，讓 IDE 自動推導。
• 容器化部署：Dockerfile `COPY --from=build /app/target/app.jar /app.jar`，`ENTRYPOINT ["java","-jar","/app.jar"]`。