Java JNI 本地調用完全指南：跨平台動態庫載入、簽名生成與部署避坑

JNI (Java Native Interface) 讓 Java 調用 C/C++ 代碼成為可能，但在跨平台動態庫命名、載入路徑、函數簽名生成等細節上藏著諸多坑。本文系統梳理 Windows (.dll) 與 Linux (.so) 的完整流程，附帶實戰避坑清單。

核心流程四步走

1. Java 端：聲明 native 方法 → javac 編譯 → javah 生成 .h 檔
2. C/C++ 端：實現 .h 中的函數簽名 → 編譯生成動態庫
3. 部署：動態庫放置於正確路徑並配置載入環境
4. 運行：System.loadLibrary 載入 → 調用 native 方法

平台差異對照表

關鍵坑點與解法

1. 套件名稱影響 JNI 函數簽名

Java 類若在套件 cn.common.testlib 中，javah 生成的 C 函數前綴為 Java_cn_common_testlib_；無套件則無前綴。建議：C 代碼中直接包含生成的 .h 檔，勿手寫簽名。

2. Windows 載入機制細節

// Java 代碼
static {
    // 必須包含 lib 前綴，副檔名可省略
    System.loadLibrary("libmylib");
    // 或使用絕對路徑載入（不受命名慣例限制）
    // System.load("C:/path/to/libmylib.dll");
}

確保 DLL 所在目錄已加入系統 PATH，或啟動參數 -Djava.library.path=... 指定。

3. Linux 載入機制細節

// Java 代碼
static {
    // 必須去掉 lib 前綴與 .so 後綴
    System.loadLibrary("mylib");
}

配置方式二選一：

• 修改 /etc/profile：export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
• 啟動參數：java -Djava.library.path=/path/to/lib ...
• 或直接放入 $JAVA_HOME/jre/lib/amd64/（不推薦，污染 JRE 目錄）

4. 編譯生成動態庫

Windows (MSVC)：

cl /I"%JAVA_HOME%\include" /I"%JAVA_HOME%\include\win32" /LD MyImpl.c /Femylib.dll

Linux (GCC)：

gcc -shared -fPIC -I"$JAVA_HOME/include" -I"$JAVA_HOME/include/linux" MyImpl.c -o libmylib.so

現代化替代方案：JNA / JNR-FFI

若不想編寫 C/C++ 胶水代碼，推薦：

• JNA (Java Native Access)：純 Java 透過 libffi 直接調用動態庫，無需編譯 C 代碼，開發效率極高
• JNR-FFI：JNA 底層使用的運行時，效能更優，支援更複雜的類型映射

// JNA 範例
public interface MyLib extends Library {
    MyLib INSTANCE = Native.load("mylib", MyLib.class);
    int myFunction(int a, double b);
}

// 直接調用
int result = MyLib.INSTANCE.myFunction(1, 2.5);

總結

JNI 雖強大但易出錯，核心在於：命名慣例跨平台一致性、載入路徑正確配置、函數簽名與 .h 檔嚴格對應。新專案優先評估 JNA，僅在極致效能或需複雜回調時使用 JNI。