本文详解 jpackage 打包时识别 ControlsFX 模块失败的根本原因：ControlsFX 的模块名为 org.controlsfx.controls 而非 controlsfx，需通过 jar --describe-module 确认真实模块名，并在 --add-modules 和 --module-path 中正确引用 JAR 文件路径。
本文详解 jpackage 打包时识别 controlsfx 模块失败的根本原因：controlsfx 的模块名为 `org.controlsfx.controls` 而非 `controlsfx`，需通过 `jar --describe-module` 确认真实模块名，并在 `--add-modules` 和 `--module-path` 中正确引用 jar 文件路径。
在使用 jpackage 构建 JavaFX 应用的原生安装包时，若引入第三方模块（如 ControlsFX），常见错误是误用模块名称或错误配置模块路径，导致 java.lang.module.FindException: Module controlsfx not found。根本问题在于：controlsfx-11.1.2.jar 并不导出名为 controlsfx 的模块，其真实模块名为 org.controlsfx.controls。
✅ 正确步骤：验证并声明 ControlsFX 模块
首先，确认 JAR 的模块声明：
jar --file=controlsfx-11.1.2.jar --describe-module
输出示例：
org.controlsfx.controls@11.1.2 jar:file:///path/to/controlsfx-11.1.2.jar!/module-info.class exports org.controlsfx.control exports org.controlsfx.control.action ... requires java.base mandated requires javafx.controls
→ 可见模块名为 org.controlsfx.controls，而非 controlsfx。
✅ 修正 jpackage 命令
将原命令中错误的 --add-modules javafx.controls,controlsfx 改为：
--add-modules javafx.controls,org.controlsfx.controls
同时，--module-path 必须分别指定 JavaFX jmod 路径和 ControlsFX JAR 路径（注意：JAR 文件本身即可作为模块路径项，无需解压）：
jpackage \ --input C:\...\target \ --add-modules javafx.controls,org.controlsfx.controls \ --module-path "C:\...\openjfx-20.0.1_windows-x64_bin-jmods\javafx-jmods-20.0.1" \ --module-path "C:\...\lib\controlsfx-11.1.2.jar" \ --win-console \ --dest C:\outputs \ --main-jar tests-1.0-SNAPSHOT.jar \ --main-class tests.App
⚠️ 注意事项：
- --module-path 可多次使用（如上），但不可合并为单个参数（--module-path a;b 在 Windows 下不被 jlink 正确解析）；
- ControlsFX JAR 必须是 模块化 JAR（含 module-info.class），11.1.2 版本满足此要求；
- 若使用非模块化 JAR（自动模块），--describe-module 会显示 No module descriptor found. Derived automatic module.，此时应改用 classpath 方式（见下文备选方案）。
✅ 备选方案：以 classpath 方式引入（适用于自动模块或调试）
若模块路径配置复杂，可将 ControlsFX JAR 放入 --input 目录下的子目录（如 lib/），jpackage 会自动将其加入 classpath：
# 假设 target/ 结构如下： # └── target/ # ├── tests-1.0-SNAPSHOT.jar # └── lib/ # └── controlsfx-11.1.2.jar
此时命令中移除 --add-modules org.controlsfx.controls 和对应 --module-path，仅保留 JavaFX 模块路径：
jpackage \ --input C:\...\target \ --add-modules javafx.controls \ --module-path "C:\...\javafx-jmods-20.0.1" \ --win-console \ --dest C:\outputs \ --main-jar tests-1.0-SNAPSHOT.jar \ --main-class tests.App
生成的 {app}.cfg 文件中将包含：
app.classpath=$APPDIR\lib\controlsfx-11.1.2.jar
该方式不依赖模块系统，兼容性更强，但无法享受 jlink 的精简运行时优势。
✅ 验证打包结果
安装生成的程序后，进入安装目录下的 runtime\bin，执行：
java --list-modules | findstr "controls"
应看到：
javafx.controls@20.0.1 org.controlsfx.controls@11.1.2
表明 ControlsFX 已成功集成进运行时镜像。
总结：jpackage 对模块名称极其敏感，切勿凭直觉命名；始终用 jar --describe-module 查证模块名；模块路径中 JAR 文件与 jmod 目录地位等同，均可直接作为 --module-path 参数；合理选择模块化集成（推荐）或 classpath 集成，兼顾可维护性与运行时效率。
