解決 java.lang.UnsatisfiedLinkError: %1 不是有效的 Win32 應用程序 — JNA 調用 DLL 位數不匹配排查指南

JNA 調用 DLL 報 UnsatisfiedLinkError: %1 不是有效的 Win32 應用程序 — 根因與解決方案

在 Windows 環境下使用 JNA (Java Native Access) 調用本地 DLL 時，最常見的啟動錯誤是：

java.lang.UnsatisfiedLinkError: %1 不是有效的 Win32 應用程序
        at com.sun.jna.Native.open(Native Method)
        at com.sun.jna.NativeLibrary.loadLibrary(NativeLibrary.java:...)
        ...

核心結論：JVM 位數 (32/64-bit) 與目標 DLL 位數不匹配。64 位 JVM 只能加載 64 位 DLL，32 位 JVM 只能加載 32 位 DLL。兩者位數必須嚴格一致。

一、快速排查清單

二、三種解決方案 (按推薦度排序)

方案 1：統一遷移至 64 位 (推薦，現代標準)

• 安裝 64 位 JDK (JDK 11/17/21 LTS 均默認 64 位)。
• 獲取或編譯 64 位版本的目標 DLL (Visual Studio 選 x64 配置編譯)。
• 確保所有傳遞依賴 (VC++ Runtime、第三方 DLL) 同為 64 位。

方案 2：強制使用 32 位 JVM (兼容舊 32 位 DLL)

• 安裝 32 位 JDK (Oracle JDK 8 仍提供 32 位安裝包，或用 Zulu/Adoptium 32 位構建)。
• IDE/構建工具/運行腳本全部指向 32 位 java.exe。
• 缺點：堆內存限制 ~1.5-2GB，無法利用現代硬體優勢，長期維護成本高。

方案 3：進程隔離 — 32 位代理進程 + IPC (不想換 JVM/換 DLL 時)

• 編寫一個 32 位 Java 進程 (或 C++/C#/Python) 專門加載 32 位 DLL，暴露 HTTP/RPC/gRPC/標準輸出 接口。
• 主應用 (64 位 JVM) 通過進程間通信調用代理進程。
• 適合「第三方只有 32 位 DLL、無源碼、主應用必須 64 位」的棘手場景。

三、代碼層面的最佳實踐

public interface MyDLL extends Library {
    // 1. 使用 JNA Platform 類型映射，避免手寫結構體對齊錯誤
    // 2. 顯式指定調用約定：StdCallLibrary (Windows API 默認) 或 Library (C 默認 cdecl)
    MyDLL INSTANCE = Native.load("MyDLL", MyDLL.class, 
        Map.of("calling-convention", StdCallLibrary.class)); // 或直接繼承 StdCallLibrary

    // 3. 複雜結構體繼承 Structure，使用 @FieldOrder 保證內存佈局
    int initDevice(int port);
    int readData(Pointer buffer, int maxLen);
    void closeDevice();
}

// 啟動時檢查位數匹配，早失敗快診斷
static {
    String arch = System.getProperty("sun.arch.data.model"); // "32" or "64"
    String dllPath = "libs/" + (arch.equals("64") ? "x64" : "x86") + "/MyDLL.dll";
    File f = new File(dllPath);
    if (!f.exists()) throw new UnsatisfiedLinkError("Missing " + arch + "-bit DLL: " + dllPath);
    System.load(f.getAbsolutePath()); // 顯式絕對路徑加載，避免 PATH 污染
}

四、進階避坑指南

1. VC++ 運行時缺失：目標機需安裝對應版本 Visual C++ Redistributable (x86/x64)，否則報 Error 126: The specified module could not be found (實際是依賴 DLL 缺失)。
2. 調用約定錯誤：Windows API 多為 stdcall (JNA 用 StdCallLibrary)，C 庫多為 cdecl (用 Library)。混用會導致棧平衡錯誤、參數亂碼、崩潰。
3. 字符串編碼：Windows API 帶 A 後綴 (ANSI/GBK)，W 後綴 (UTF-16)。JNA 默認 W 版本，傳 String 自動轉 UTF-16；若需 ANSI，用 Native.toByteArray(str, "GBK") 手動轉 byte[] 或 Pointer。
4. 併發安全：DLL 內部若非線程安全，Java 端需加鎖或用 ThreadLocal 獨享實例。

五、總結

UnsatisfiedLinkError: %1 不是有效的 Win32 應用程序 99% 是 JVM/DLL 位數不匹配。現代項目強烈建議全鏈路 64 位化：64 位 JDK + 64 位 DLL + 64 位依賴。若受限於廠商只提供 32 位 DLL，採用進程隔離代理模式隔離風險，避免主應用被迫降級為 32 位 JVM。