如何通过jpackage将集成HSQLDB的JavaFX应用打包为exe

问题根因 #

该错误本质是jlink构建自定义运行时镜像阶段，没有正确纳入HSQLDB相关模块及服务依赖，导致模块路径解析失败：

• IDE内执行gradle run时使用全量JDK+Gradle自动拼接的完整模块路径，不会触发模块裁剪逻辑，因此运行正常
• org.beryx.jlink插件默认按静态依赖扫描裁剪模块，HSQLDB作为带自动模块名的JDBC驱动，其服务提供者配置不会被默认扫描纳入，同时插件低版本存在自动模块路径排序bug，会导致主模块被排除在Boot Layer之外

修复步骤 #

1. 升级jlink插件版本+显式配置模块规则 #

首先将build.gradle中org.beryx.jlink插件升级至2.26.0及以上版本，避免低版本自动模块处理bug，同时在jlink配置块中显式声明模块、绑定JDBC服务：

plugins {
    id 'java'
    id 'application'
    id 'org.openjfx.javafxplugin' version '0.0.13'
    id 'org.beryx.jlink' version '2.26.0' // 必须升级到2.25.0以上
}

// 原有javafx、repositories、dependencies配置保持不变，HSQLDB依赖保留implementation("org.hsqldb:hsqldb:2.6.1")

jlink {
    options = ['--strip-debug', '--compress', '2', '--no-header-files', '--no-man-pages']
    launcher {
        name = 'HelloWorldApp'
        mainClass = 'my.openjfx.hellofx.HelloApplication' // 显式指定主类，禁止插件自动扫描
    }
    // 显式声明所有需要纳入自定义镜像的模块，禁止插件自动裁剪漏依赖
    addModules = ['my.openjfx.hellofx', 'org.hsqldb', 'java.sql', 'java.naming']
    // 绑定JDBC驱动服务，确保HSQLDB的驱动实现能被JVM识别
    addOptions '--bind-services'
    
    jpackage {
        // 原有jpackage配置（安装包选项、图标、输出路径等）保持不变
        installerType = 'exe'
        imageOptions = ['--win-dir-chooser', '--win-menu', '--win-shortcut']
    }
}

如果需要控制打包体积，可去掉--bind-services，替换为显式指定HSQLDB驱动服务：

addOptions '--add-services', 'java.sql.Driver'

2. 补全module-info.java的依赖声明 #

很多场景下漏写java.sql模块依赖会导致jlink阶段裁剪掉JDBC模块，连带HSQLDB和主模块解析失败，正确配置参考：

module my.openjfx.hellofx {
    requires javafx.controls;
    requires javafx.fxml;
    requires org.hsqldb;
    requires java.sql; // 必须显式声明，HSQLDB依赖JDBC核心接口

    // 原有FXML反射开放配置保持不变
    opens my.openjfx.hellofx to javafx.fxml;
    exports my.openjfx.hellofx;
}

3. 全量清理缓存后重新打包 #

必须清空之前构建生成的错误jlink镜像缓存，否则配置修改不会生效，在IDEA终端执行Windows平台命令：

gradlew.bat clean cleanJlinkBase jlink jpackage

校验方法 #

打包完成后，先进入生成的jlink镜像bin目录，执行命令验证模块是否正确纳入：

java --list-modules

输出结果中包含my.openjfx.hellofx、org.hsqldb两个模块时，再启动exe即可正常运行，不会出现Boot Layer相关错误。

常见避坑点 #

• 不要将HSQLDB依赖声明为runtimeOnly，必须使用implementation，否则jlink插件扫描模块路径时无法识别该jar
• 不要手动修改jlink生成的build/jlinkbase目录下的模块配置，所有规则通过gradle配置声明
• 若使用JDK17及以上版本，不要混用x86和x64架构的JDK与依赖，否则模块解析时会出现静默失败

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