Android 專案引用導致 Private Libraries 消失？JAR 包丟失的排查與修復

現象描述

專案 A 引用專案 B 作為 Library 後，專案 B 原本在 Android Private Libraries 下的 JAR 包消失，取而代之的是空文件夾圖標，JAR 內部類文件無法訪問，編譯報 ClassNotFoundException 或 NoClassDefFoundError。

根因定位

當專案被標記為 Library (isLibrary=true) 時，其構建產出為 .aar，不再生成 Private Libraries 容器。原本放在 libs/ 目錄下的 JAR 若未在 build.gradle 中聲明為 implementation files('libs/xxx.jar')，將不會被打包進 AAR，導致引用方找不到類。

修復步驟

1. 檢查 Library 專案的 build.gradle：

   dependencies {
       implementation fileTree(dir: 'libs', include: ['*.jar']) // 確保此行存在
       // 或顯式聲明
       implementation files('libs/specific.jar')
   }
   

2. 同步並清理： File > Sync Project with Gradle Files → Build > Clean Project → Rebuild Project。
3. 驗證 AAR 產出： 在 library/build/outputs/aar/ 解壓生成的 .aar，確認 classes.jar 包含目標類，且 libs/ 下的 JAR 已合併。
4. 引用方檢查： 確保引用方 dependencies { implementation project(':library') } 正確，且未重複排除傳遞依賴。

常見誤區

• ❌ 以為 Android Private Libraries 是自動生成的運行時容器 —— 它只是 ADT/早期 Gradle 時代的視圖產物，現代構建完全依賴 Gradle 依賴圖。
• ❌ 手動將 JAR 複製到引用方 libs/ —— 會導致類重複、版本衝突，違反單一職責原則。

最佳實踐

• 將第三方 JAR 發布至私有 Maven 倉庫（Nexus/Artifactory），Library 與 App 均通過坐標引用。
• 若必須本地 JAR，統一放在 Library 模組 libs/ 並在 build.gradle 聲明，利用 api (舊 compile) 實現傳遞依賴。
• 定期執行 ./gradlew dependencies --configuration releaseRuntimeClasspath 檢查依賴樹，確保 JAR 正確傳遞。

理解「Library 模組輸出 AAR、依賴傳遞靠 Gradle 配置」的現代構建機制，Private Libraries 消失就不再是謎。