解決 Eclipse/Android 項目 Add External JARs 導致 NoClassDefFoundError 的根因與修復

問題現象

在 Eclipse 中對 Android 項目反覆執行 Add External JARs / Remove JARs 後，代碼編譯通過，但運行時觸碰到該 JAR 中的類拋出 java.lang.NoClassDefFoundError，導致應用崩潰。

根因分析

1. 缺失 Android Dependencies 庫

對比正常項目發現，故障項目 Java Build Path → Libraries 下缺少 Android Dependencies 容器條目。

2. .classpath 文件關鍵屬性被篡改

定位到項目根目錄 .classpath 文件，發現關鍵條目：

<classpathentry exported="false" kind="con" path="com.android.ide.eclipse.adt.LIBRARIES"/>

關鍵點：exported="false" 導致依賴不參與打包輸出（APK 中不包含該 JAR 的類），運行時自然找不到類。

修復方案

方案一：修正 .classpath（推薦）

1. 關閉 Eclipse
2. 編輯項目根目錄 .classpath，將上述條目改為：
   <classpathentry exported="true" kind="con" path="com.android.ide.eclipse.adt.LIBRARIES"/>
3. 重新啟動 Eclipse，項目自動刷新，Android Dependencies 庫恢復

方案二：規範 JAR 放置位置（根治）

核心原則：所有第三方 JAR 必須放置在項目 libs/ 目錄下。

• Eclipse + ADT 會自動掃描 libs/ 並加入 Android Dependencies
• 打包工具（AAPT/AAPT2）會自動將 libs/ 下所有 JAR 打入 APK
• 若 JAR 放在項目外部或其他目錄，雖可通過 Build Path 編譯，但 不會被打包，導致運行時缺失

深度原理解析

為什麼 exported="true" 至關重要？

exported 屬性控制該類路徑條目是否對「依賴此項目的其他項目」或「打包輸出」可見。ADT 的 LIBRARIES 容器聚合了 libs/ 下所有 JAR，只有 exported="true" 才會：

1. 參與編譯時類路徑
2. 參與 dx 工具將 .class 轉 .dex
3. 最終打入 classes.dex 進 APK

為什麼反覆 Add/Remove 會導致 exported 變 false？

ADT 版本與 Eclipse 版本協同存在已知 Bug：通過 GUI 反覆操作外部 JAR 時，.classpath 寫入邏輯錯誤地將容器條目標記為 exported="false"。此問題在 ADT 22.6+ / Eclipse 4.3+ 較常見。

最佳實踐清單

遷移建議：Gradle + Android Studio

現代 Android 開發已全面遷移至 Gradle 構建 + Android Studio，依賴管理通過 build.gradle 聲明：

dependencies {
    implementation files('libs/local-lib.jar')     // 本地 JAR
    implementation 'com.squareup.okhttp3:okhttp:4.9.0' // 遠程坐標
}