Java UnsatisfiedLinkError 加载 Native 库失败

这个错本质是「Java 想调 C/C++ 写的本地方法，结果没接上头」。它给出的信息有限——一句 no xxx in java.library.path 或 Library not found——所以第一步要做的是沿「找不到库 → 找到了但方法/架构不对 → 库自身依赖缺失」的顺序排查，而不是直接上手改代码。

Issue & Env（案发现场与环境）

现象：启动时类初始化加载 native 库失败，进程退出；或首次调用 native 方法时抛错。
环境：使用 JNI 或依赖带 native 库的三方包（TIBCO、OpenCV、Netty 的 epoll 等），Windows .dll / Linux .so / macOS .dylib。

StackTrace（堆栈日志）

最经典的一种：

Exception in thread "main" java.lang.UnsatisfiedLinkError: no HelloNative in java.library.path
	at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1867)
	at java.lang.Runtime.loadLibrary0(Runtime.java:870)
	at java.lang.System.loadLibrary(System.java:1122)
	at com.example.NativeDemo.<clinit>(NativeDemo.java:9)

也有库找到了、但依赖的另一个库缺了：

java.lang.UnsatisfiedLinkError: /path/to/libfoo.so: libbar.so: cannot open shared object file: No such file or directory
    at java.lang.ClassLoader$NativeLibrary.load(Native Method)
    at java.lang.ClassLoader.loadLibrary0(ClassLoader.java:1934)
    at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1822)
    at java.lang.Runtime.loadLibrary0(Runtime.java:870)
    at java.lang.System.loadLibrary(System.java:1122)
    at com.example.NativeDemo.<clinit>(NativeDemo.java:9)

Reproduce（复现代码）

声明 native 方法并用 System.loadLibrary 加载：

public class NativeDemo {
    public native void sayHello();

    static {
        System.loadLibrary("HelloNative");
    }

    public static void main(String[] args) {
        new NativeDemo().sayHello();
    }
}

若 libHelloNative.so 不在 JVM 能找到的路径里，启动就报上面的错。

Root Cause（根因分析）

JVM 只从 java.library.path 这个系统属性（以及 Linux 下的 LD_LIBRARY_PATH）列出的目录里找本地库，库文件不在这些路径，就报 no xxx in java.library.path。

搞错的原因集中在这几类：

库名拼错或不带扩展名——System.loadLibrary("HelloNative") 会自动按平台补成 libHelloNative.so、HelloNative.dll，你手上文件若叫别的名字就对不上。
库的架构和 JVM 不匹配——32 位 JVM 加载不了 64 位的 .so，反之亦然。
库自身还依赖别的 native 库，那个依赖没装、没在 LD_LIBRARY_PATH 里。
库里确实没有你要调的那个 native 方法——C 侧符号名改了，或没导出。

「把库拷到某个目录」但没加到 java.library.path 是最常见的徒劳操作：JVM 不会去那个任意目录找，只会去它列表里的位置。

The Fix（解决方案）

先确认库到底在哪、JVM 到底去哪找：

System.out.println(System.getProperty("java.library.path"));

然后把库所在目录显式塞进搜索路径：

java -Djava.library.path=/path/to/lib -jar app.jar
# Linux 也可用环境变量
export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH

用 System.load() 传绝对路径能绕过路径查找，但生产代码别这么写，路径在不同机器、容器里都不一样，会破坏可移植性：

System.load("/path/to/lib/libHelloNative.so"); // 不推荐用于生产

库名对不上就核对文件的实际命名和 loadLibrary 传的名字；架构对不上就换匹配 JVM 架构的库；库自身的依赖缺了，用 ldd /path/to/libfoo.so（Linux）看哪些依赖 not found，再补装对应的系统包，Docker 里要把装依赖写进 Dockerfile。最后确认 C 侧符号名和 Java 侧 native 方法按 JNI 命名规则一致，别在导出符号上改名。