Android 視頻播放器載入 .so 庫失敗：UnsatisfiedLinkError 排查清單

錯誤現象

點擊播放視頻時拋出 java.lang.UnsatisfiedLinkError，靜態區塊載入 stlport_shared、hdcore、hdutil 等 .so 庫失敗。

常見原因與解決步驟

1. jniLibs 目錄架構錯誤

專案結構需為：

src/main/jniLibs/
├── arm64-v8a/
│   ├── libstlport_shared.so
│   ├── libhdcore.so
│   └── ...
├── armeabi-v7a/
│   └── ...
├── x86/
│   └── ...
└── x86_64/
    └── ...

• 確認**目標裝置 CPU 架構**對應的資料夾內確實包含所有需求的 .so 檔案。
• 缺少特定架構（如 arm64-v8a）會導致 64 位裝置載入失敗。

2. build.gradle 未配置 jniLibs 路徑

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

或將 .so 放入 src/main/jniLibs 並確保 Gradle 同步後在 APK 的 lib/<abi>/ 目錄下可見。

3. 依賴順序錯誤

.so 之間有依賴關係（如 hdcore 依賴 stlport_shared），**必須先載入被依賴的庫**：

static {
    System.loadLibrary("stlport_shared"); // 基礎庫最先
    System.loadLibrary("hdcore");
    System.loadLibrary("hdutil");
    System.loadLibrary("hdsdl");
    System.loadLibrary("hdjpeg");
    System.loadLibrary("hdacodec");
    System.loadLibrary("hdplayer");
    native_init();
}

4. 使用舊版 NDK 需啟用相容模式

在 gradle.properties 加入：

android.useDeprecatedNdk=true

並確認 build.gradle 的 ndkVersion 與 .so 編譯環境一致。

5. 封裝 APK 時 .so 被壓縮/剝離

android {
    packagingOptions {
        doNotStrip "*/lib*.so"  // 保留符號表
        jniLibs {
            useLegacyPackaging = true  // AGP 4.1+ 需此行防止 .so 被壓縮
        }
    }
}

6. 檢查 APK 內容確認 .so 確實打包

• 將輸出的 .apk 改名為 .zip 解壓，查看 lib/arm64-v8a/ 等目錄是否包含所有 .so。

快速驗證腳本

// 在 Application 或首個 Activity 的 onCreate 最早處加入
static {
    try {
        System.loadLibrary("stlport_shared");
        Log.d("SO_TEST", "stlport_shared loaded OK");
    } catch (UnsatisfiedLinkError e) {
        Log.e("SO_TEST", "load failed: " + e.getMessage());
    }
}

總結

優先檢查 jniLibs 架構完整性、Gradle 配置、載入順序。若仍失敗，用 logcat 擷取完整堆疊，確認缺少哪個具體 .so 或符號，再對應補齊。