JNA能自动加载主库，但无法接管其依赖库（如.so/.dylib/.dll）的递归查找；真正决定依赖解析路径的是操作系统原生动态链接器（如dyld、ld-linux、LoadLibraryEx），因此必须通过环境变量（如DYLD_LIBRARY_PATH、LD_LIBRARY_PATH、PATH）显式告知系统依赖库所在位置。
jna能自动加载主库，但无法接管其依赖库（如`.so`/`.dylib`/`.dll`）的递归查找；真正决定依赖解析路径的是操作系统原生动态链接器（如`dyld`、`ld-linux`、`loadlibraryex`），因此必须通过环境变量（如`dyld_library_path`、`ld_library_path`、`path`）显式告知系统依赖库所在位置。
在使用 JNA 加载一个带有复杂原生依赖链的动态库（例如 libstellarsolver.dylib 依赖 libcfitsio.4.dylib、libwcs5.dylib 等）时，开发者常陷入一个典型误区：误以为 JNA 负责整个依赖树的加载与解析。实际上，JNA 仅完成第一步——调用 dlopen()（macOS/Linux）或 LoadLibrary()（Windows）加载你指定的主库。一旦该库内部引用了其他共享库，后续的符号解析和依赖加载即完全移交操作系统原生链接器，JNA 不再介入，也不会自动将 jna.library.path 注入到原生搜索路径中。
这意味着：即使你已通过 jna.library.path=/tmp/native 正确放置了所有 .dylib 文件，并看到 libstellarsolver.dylib 成功被 JNA 找到，只要其依赖项（如 @executable_path/../Frameworks/libcfitsio.4.dylib）在系统默认路径中不存在，dlopen 就会直接失败——且日志中绝不会显示“正在尝试从 /tmp/native 查找 libcfitsio.4.dylib”，因为那根本不在它的搜索范围内。
✅ 正确解法：让原生链接器“看见”你的依赖目录
不同平台需设置对应环境变量，在 JVM 启动前生效（不可在 Java 运行时通过 System.setProperty() 修改）：
| 平台 | 关键环境变量 | 推荐设置方式（示例） |
|---|---|---|
| macOS | DYLD_LIBRARY_PATH |
export DYLD_LIBRARY_PATH="/tmp/native:$DYLD_LIBRARY_PATH" |
DYLD_FALLBACK_LIBRARY_PATH |
（可选备用）export DYLD_FALLBACK_LIBRARY_PATH="/tmp/native:/usr/local/lib"
|
|
| Linux | LD_LIBRARY_PATH |
export LD_LIBRARY_PATH="/tmp/native:$LD_LIBRARY_PATH" |
| Windows | PATH |
set PATH=C:\temp\native;%PATH%（注意：Windows 下 jna.library.path 本身即映射到 PATH） |
⚠️ 注意事项：
- macOS 上
DYLD_*变量在 SIP（系统完整性保护）启用时对系统进程受限，但对普通 Java 应用（如java -jar app.jar）完全有效；- 若依赖库位于子目录（如
Frameworks/），请确保环境变量指向包含该子目录的父路径（如/tmp/native，而非/tmp/native/Frameworks），否则@rpath/Frameworks/xxx.dylib仍无法解析；- 在打包为
.jar或 Spring Boot fat jar 时，建议在启动脚本中自动解压 native 依赖到临时目录，并动态设置环境变量（可用Files.createTempDirectory("jna-deps")+System.setProperty("jna.tmpdir", ...)配合）。
? 实战示例（macOS）：
# 1. 解压所有 native 库到临时目录 mkdir -p /tmp/stellarsolver-deps tar -xf stellarsolver-native-macos.tar.gz -C /tmp/stellarsolver-deps # 2. 设置原生链接器路径（关键！） export DYLD_LIBRARY_PATH="/tmp/stellarsolver-deps:$DYLD_LIBRARY_PATH" # 3. 启动应用（此时 libstellarsolver.dylib 及其所有 transitive deps 均可解析） java -Djna.debug_load=true -jar stellar-app.jar
同时，Java 侧保持标准 JNA 接口定义即可，无需为每个依赖单独 Native.load()：
public interface StellarSolver extends Library {
StellarSolver INSTANCE = Native.load("stellarsolver", StellarSolver.class);
int solve(String imagePath, Pointer result);
}
? 总结：JNA 是“门卫”，只负责打开第一扇门；而门后的走廊（依赖链）由操作系统自己导航。要让导航成功，你得提前把地图（环境变量）交给操作系统——这不是 JNA 的缺陷，而是跨语言调用中职责边界的合理划分。掌握这一原理，就能彻底告别 Library not loaded: xxx.dylib 类错误，实现健壮、可移植的本地库集成。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
