Android Studio 最新版導入 .so 動態庫完整指南

問題背景

近期將 Android Studio 升級至最新版本後，許多開發者發現原本在 build.gradle 中配置 sourceSets { main { jniLibs.srcDirs = ['libs'] } } 導入 .so 文件的方式失效。典型目錄結構為 main/jniLibs/armeabi/libvideoencoder.so，但構建過程中仍報找不到動態庫。

核心原因分析

Android Gradle Plugin 3.0+ 版本對 NDK 集成進行了重大調整：

• 不再推薦使用 jniLibs.srcDirs 手動指定目錄
• 預期 .so 文件放置於 src/main/jniLibs/<abi>/ 標準目錄下
• 若使用 CMake 或 ndk-build，產物會自動打包，無需額外配置

解決方案

方案一：遵循標準目錄結構（推薦）

project/
├── app/
│   ├── src/
│   │   ├── main/
│   │   │   ├── jniLibs/
│   │   │   │   ├── arm64-v8a/
│   │   │   │   ├── armeabi-v7a/
│   │   │   │   ├── x86/
│   │   │   │   └── x86_64/
│   │   │   │       └── libvideoencoder.so

移除 build.gradle 中的 sourceSets 配置，直接同步項目即可。

方案二：使用 CMake 管理原生庫

# CMakeLists.txt
add_library(videoencoder SHARED IMPORTED)
set_target_properties(videoencoder PROPERTIES IMPORTED_LOCATION
    ${CMAKE_SOURCE_DIR}/src/main/jniLibs/${ANDROID_ABI}/libvideoencoder.so)

target_link_libraries(native-lib videoencoder log)

在 build.gradle 中配置 externalNativeBuild.cmake.path，Gradle 會自動處理打包。

方案三：兼容舊版配置（不推薦長期使用）

android {
    sourceSets {
        main {
            jniLibs.srcDirs = ['src/main/jniLibs']
        }
    }
}

注意：路徑需指向 jniLibs 父目錄，而非具體 ABI 子目錄。

版本兼容性說明

常見避坑指南

1. ABI 名稱匹配：確保 .so 文件放置於正確的架構目錄（如 armeabi-v7a 而非 armeabi）
2. 依賴傳遞：若 .so 依賴其他動態庫，需一同打包或確保系統已存在
3. Strip 處理：Release 構建會默認 strip 符號表，調試時建議保留 debug 版本
4. 多模塊項目：庫模塊需在 build.gradle 中聲明 android { defaultConfig { ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' } } }

驗證方法

構建 APK 後，使用 unzip -l app/build/outputs/apk/debug/app-debug.apk | grep .so 確認動態庫是否正確打包至 lib/<abi>/ 目錄。

總結

現代 Android 開發強烈建議遷移至 CMake 管理原生庫，這不僅解決了導入問題，還能獲得更好的構建緩存、增量編譯和跨平台支持。若維護舊項目，請確保目錄結構符合最新規範，並逐步規劃遷移路線。