Java UnsatisfiedLinkError: java.library.path 中缺少库

症状

即便 libfoo.so 确实存在，JVM 仍报 UnsatisfiedLinkError: no libfoo in java.library.path。它常与平台相关：在开发机正常，却在 CI 或服务器上失败。

诊断

打印搜索路径并核验文件：

java -Djava.library.path=/opt/native -jar app.jar
file /opt/native/libfoo.so
ldd /opt/native/libfoo.so | grep "not found"

ldd 会暴露 JVM 报错中未提及的缺失传递依赖库。

修复

显式设置路径或以绝对路径加载：

System.load("/opt/native/libfoo.so"); // absolute path
// or -Djava.library.path=/opt/native on the command line

安装缺失的系统包，并提供架构匹配的构建产物。

验证

在各目标平台上重跑本地调用；库成功加载、JNI 方法正常执行，且 ldd 不再报告 not found。