Android 動態庫加載失敗 (System.load) 排查實戰：JNI 方法聲明缺失導致符號表不匹配

問題現象

• 同一目錄下，某些 .so 庫可正常 System.load，但特定庫拋出 UnsatisfiedLinkError: dlopen failed: library not found 或 JNI_OnLoad not found。
• 文件路徑、名稱、權限 (chmod 755) 均確認無誤。
• System.loadLibrary (不帶路徑) 同樣失敗。

根因深度解析

Android 動態庫加載機制：

1. System.load 打開庫文件，調用其 JNI_OnLoad 函數。
2. JNI_OnLoad 中通常調用 RegisterNatives 註冊 JNI 方法映射表。
3. **關鍵點**：RegisterNatives 要求 **Java 端對應的 native 方法必須已聲明且簽名完全一致**。若 Java 類缺少某個 native 方法聲明，或簽名不匹配 (參數類型、返回類型、方法名)，RegisterNatives 失敗，導致 JNI_OnLoad 返回錯誤碼，系統隨即卸載庫，拋出「庫未找到」或「符號缺失」誤導性錯誤。

排查步驟

1. 反編譯 .so 確認導出符號

# Linux/Mac
nm -D yourlib.so | grep JNI
# 或
objdump -T yourlib.so | grep Java

# Windows (使用 GNU 工具鏈)
dumpbin /EXPORTS yourlib.dll | findstr Java

輸出示例：Java_com_example_MyClass_nativeMethod — 對應 Java 類 com.example.MyClass 的 nativeMethod。

2. 核對 Java 端聲明

確保 **每一個導出的 JNI 函數在 Java 類中都有對應的 native 聲明**，且：

• 包名、類名、方法名**完全一致** (區分大小寫)。
• 參數類型映射正確：jint↔int、jstring↔String、jobject↔對應類、jarray↔數組類型。
• 返回類型映射正確。
• static { System.loadLibrary("yourlib"); } 塊在類中存在且執行前調用。

3. 常見遺漏場景

• C++ 代碼新增了 JNI 函數，Java 端忘記同步添加 native 聲明。
• Java 重構修改了包名/類名/方法名，C++ 未同步更新。
• 簽名中包含內部類 (如 Outer$Inner)，C++ 符號需用 Outer_00024Inner (美元符號轉義)。
• 重載方法：C++ 無重載，需在 Java 端用不同方法名對應不同 C++ 函數。

解決方案：補全聲明並驗證

package com.example;

public class MyClass {
    static {
        System.loadLibrary("mylib"); // 或 System.load("/full/path/libmylib.so")
    }

    // 對應 C++: Java_com_example_MyClass_init
    public native int init(String configPath);

    // 對應 C++: Java_com_example_MyClass_processData
    public native byte[] processData(byte[] input, int mode);

    // 切勿遺漏任何 C++ 導出的 JNI 函數對應聲明
}

進階驗證技巧

• 在 JNI_OnLoad 中添加日誌輸出每個 RegisterNatives 結果。
• 使用 adb logcat | grep -i jni 觀察詳細錯誤信息 (如 RegisterNatives failed for ...)。
• 單元測試：編寫 Java 測試類逐個調用 native 方法，定位具體失敗點。

總結

**「同目錄其他庫能加載，只有這個不能」的核心原因，90% 是 Java 端 JNI 方法聲明缺失或簽名不匹配導致 RegisterNatives 失敗，而非文件系統問題。** 重點檢查 Java 與 C++ 符號表的一致性，補全聲明即可解決。