Java 呼叫 GDAL 原生庫（DLL/JNI）完整實戰指南

GDAL（Geospatial Data Abstraction Library）是地理空間資料處理的標準庫，Java 專案若需使用其強大的矢量/格網讀寫、投影轉換功能，必須透過 JNI（Java Native Interface）載入原生動態庫。本文記錄從編譯 GDAL 到 Java 整合驗證的完整步驟與常見坑點。

一、環境準備與 GDAL 編譯

1. 下載 GDAL 原始碼（建議穩定版，如 3.8.x）。
2. Windows 環境建議使用 nmake /f makefile.vc 編譯；Linux/macOS 執行 ./configure --with-java && make。
3. 編譯產出關鍵檔案：
   • gdaljni.dll (Windows) / libgdaljni.so (Linux) — JNI 橋接庫
   • gdal.jar — Java API 封裝類別
   • gdal_*.dll/so — GDAL 核心依賴庫

二、原生庫部署策略

方案 A：放入 JRE 目錄（快速測試）

將 gdaljni.dll 及所有 GDAL 依賴 DLL 複製到 {JAVA_HOME}/jre/bin（JDK 8）或 {JAVA_HOME}/bin（JDK 9+）。

缺點：污染系統 JRE，多專案版本衝突風險高，生產環境不推薦。

方案 B：專案獨立管理（推薦生產）

1. 在專案建立 lib/native/win32-x86 或 linux-x64 目錄存放原生庫。
2. 啟動參數指定庫路徑：-Djava.library.path=lib/native/win32-x86。
3. 或使用 System.setProperty("java.library.path", path) 在載入前動態設定（需配合 Field 反射修改 sys_paths 生效）。

三、Java 專案整合與驗證

1. 將 gdal.jar 加入 Classpath（Maven 專案可 mvn install:install-file 安裝至本地倉庫）。
2. 編寫可用性檢測程式碼：

@Override
protected boolean doIsAvailable() throws Throwable {
    try {
        // 載入 JNI 橋接庫，會自動連帶載入 gdal 核心庫
        System.loadLibrary("gdaljni");
        // 簡單驗證 GDAL 版本
        System.out.println("GDAL Version: " + gdal.VersionInfo("RELEASE_NAME"));
        return true;
    } catch (UnsatisfiedLinkError e) {
        System.err.println("GDAL 載入失敗: " + e.getMessage());
        return false;
    }
}

四、常見問題排查

五、進階：Maven 專案自動化原生庫管理

使用 maven-nar-plugin 或 maven-shade-plugin 將原生庫打包進 JAR，運行時自動解壓至臨時目錄並載入，實現「單一 Fat JAR」部署。

六、總結

1. GDAL Java 綁定依賴 JNI，核心是 gdaljni 原生庫與 gdal.jar。
2. 開發期可放入 JRE bin 目錄快速驗證；生產環境建議專案隔離管理 java.library.path。
3. 位數一致性（JDK/GDAL/OS）是避免 UnsatisfiedLinkError 的關鍵。