UnsatisfiedLinkError本质是JVM加载本地库失败，需按路径→文件→依赖→架构四层顺序排查：确认java.library.path含库目录、库名严格匹配平台规范（如loadLibrary("xxx")对应libxxx.so）、依赖库完整（用ldd/otool/dumpbin检查）、JVM与库架构一致（32/64位、ARM/x86）。
UnsatisfiedLinkError 不是 Java 代码写错了，而是 JVM 找不到、打不开或用不了本地库（.so/.dll/.dylib）。直接按路径→文件→依赖→架构四层顺序查，90% 的问题当场定位。
确认 java.library.path 是否真包含你的库目录
JVM 只认 java.library.path 里的路径，不看当前目录、resources、jar 包内部，也不走系统级的 LD_LIBRARY_PATH（Linux/macOS）或 PATH（Windows）——除非你显式配置了它。
- 运行时加参数指定：
-Djava.library.path=/opt/myapp/lib:/usr/local/lib（Linux/macOS 冒号分隔，Windows 分号） - 代码里打印验证：
System.out.println(System.getProperty("java.library.path"))，核对输出是否真有你放库的目录 - 别把
libxxx.so放进src/main/resources——JVM 不会从这里加载；也别打包进 jar ——System.loadLibrary()不支持从 jar 解压加载
检查库文件名和大小写是否严格匹配
System.loadLibrary("xxx") 在 Linux/macOS 上找的是 libxxx.so，Windows 上找的是 xxx.dll，macOS 还可能是 libxxx.dylib。名字错一个字符、大小写差一点，就“找不到”。
- 写成
loadLibrary("libxxx")是错的——JVM 会去找liblibxxx.so，根本不存在 - Linux/macOS 文件系统区分大小写：
LibXXX.so和libxxx.so是两个文件 - 用
ls -l /your/path/libxxx.so（Linux/macOS）或dir C:\path\xxx.dll（Windows）确认文件真实存在
用 ldd/otool/dumpbin 检查库依赖是否完整
即使主库文件在路径里，若它依赖的其他动态库缺失，dlopen 仍失败，报错常含 “not found” 或 “cannot open shared object file”。
- Linux：
ldd libxxx.so，看有没有 “not found” 行；缺失的库需补到LD_LIBRARY_PATH或/etc/ld.so.conf - macOS：
otool -L libxxx.dylib，缺失项可用install_name_tool修正或补全路径 - Windows：用
dumpbin /dependents xxx.dll（需 Visual Studio 工具链），重点确认 VC++ 运行时（如vcruntime140.dll）是否在PATH中
验证 JVM 和本地库架构是否一致
32 位 JVM 只能加载 32 位库，64 位同理。不匹配时错误可能不提示位数，只报 “dlopen failed” 或 “wrong ELF class”。
- 查 JVM 位数：
java -version看是否有 “64-Bit”；或代码中System.getProperty("os.arch") - 查库文件位数：Linux 上用
file libxxx.so，看输出是否含 “ELF 64-bit” 或 “32-bit” - 特别注意 OpenJDK 11.0.24+ 官方二进制包：它默认链接较新
libz.so.1和libstdc++.so.6，在 CentOS 7.6、Ubuntu 18.04 等老系统上会静默失败，连java -version都过不去
最容易被忽略的是 ABI 兼容性——比如 OpenJDK 自带的 libfontmanager.so 依赖 libfreetype.so.6，但精简 Docker 镜像里根本没装字体库；又比如麒麟系统用 ARM 架构却装了 x86 版 JDK。这类问题不会报“找不到 xxx.so”，而是在加载链最底层崩溃，必须用 strace -e trace=openat,openat2 或 LD_DEBUG=libs 追到底层系统调用才能看清真正卡在哪一步。
