基于Corretto15与OpenJFX17的JavaFX程序本机可运行其他设备报JNI错误

常见成因 #

• JRE版本不兼容：本地使用Corretto 15编译项目，如果目标设备的JRE版本低于15，类文件版本号不匹配会触发JNI调用错误；同时OpenJFX 17对最低JRE版本有要求，版本过低也会导致JNI层面调用失败。
• OpenJFX原生库不匹配：OpenJFX依赖包含对应操作系统（Windows/macOS/Linux）、CPU架构（x86/ARM）的原生动态库，本地打包时如果仅包含当前设备的原生库，迁移到其他架构/系统的设备时，JNI调用无法找到对应库就会抛出错误。
• 打包配置缺失：本地IntelliJ运行时会自动加载配置好的OpenJFX依赖，若打包时未将OpenJFX依赖一起打包到产物中，目标设备又未单独配置OpenJFX环境，就会出现JNI调用找不到类/方法的问题。
• 模块化配置错误：如果项目使用Java模块化（module-info.java），打包时未正确指定模块路径、主类模块名，或是模块声明中缺失OpenJFX相关模块的依赖，运行时也会触发JNI错误。

解决方法 #

• 统一运行环境版本

优先保证本地编译用的JDK版本与目标设备的运行环境版本一致，可选择自带OpenJFX绑定的JDK发行版（如BellSoft Liberica JDK、Azul Zulu JDK FX版本），避免单独配置OpenJFX环境的问题。如果继续使用Corretto 15，需确保目标设备安装的JRE版本不低于15，且与本地编译用的Corretto 15小版本尽量一致。

• 引入全平台OpenJFX依赖
  如果使用Maven/Gradle管理依赖，需要引入所有目标平台对应的OpenJFX分类器依赖，例如Maven配置中为每个目标平台添加<classifier>标签（可选值包括win、mac、linux、mac-aarch64等），确保打包时所有目标平台的原生库都被打入产物。
• 使用规范的打包流程
  不要直接使用IntelliJ默认的Jar构建功能，推荐使用jlink或jpackage工具，将JRE、OpenJFX依赖、项目代码一起打包为对应平台的可执行程序，目标设备无需单独安装Java环境即可直接运行。如果需要生成可执行Jar包，要确保MANIFEST.MF中正确指定主类，所有依赖的OpenJFX类库都被打入Jar包的lib目录，运行时使用如下命令启动：
  java --module-path 你的lib目录路径 --add-modules 你用到的OpenJFX模块,你的项目模块名 -jar 你的jar包名.jar
• 校验模块化配置
  如果项目使用了module-info.java，确保文件中声明了所有用到的OpenJFX模块依赖（例如requires javafx.controls; requires javafx.fxml;），同时将需要反射调用的包开放给JavaFX组件，例如opens 你的业务包名 to javafx.fxml;。

内容的提问来源于stack exchange，提问作者Sainsy