使用 jpackage 打包含 controlsfx 的 javafx 应用时，常见错误是模块名误写或模块路径配置不当；本文详解如何通过 --add-modules 和 --module-path 正确声明 controlsfx 模块，并提供验证与备选方案。
使用 jpackage 打包含 controlsfx 的 javafx 应用时，常见错误是模块名误写或模块路径配置不当；本文详解如何通过 --add-modules 和 --module-path 正确声明 controlsfx 模块，并提供验证与备选方案。
在 Java 11+ 及模块化 JavaFX 生态中，ControlsFX 并非默认 JDK 模块，也不以 controlsfx 为模块名——这是导致 java.lang.module.FindException: Module controlsfx not found 的根本原因。ControlsFX 自 v11 起已完全模块化，其真实模块名为 org.controlsfx.controls（可通过 jar --describe-module 精确验证）。
✅ 正确配置 jpackage 命令的关键点
-
确认 ControlsFX JAR 的模块名
在终端执行（路径替换为你本地的 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.textfield requires java.base requires javafx.controls ...
→ 注意首行明确声明模块名为 org.controlsfx.controls。
-
修正 jpackage 命令
- --add-modules 中必须使用完整模块名：javafx.controls,org.controlsfx.controls
- 每个 --module-path 后需紧跟对应路径（不可重复写 --module-path）；ControlsFX JAR 本身即可作为模块路径项（无需解压或指向目录）：
jpackage \ --input C:\your\project\target \ --add-modules javafx.controls,org.controlsfx.controls \ --module-path "C:\path\to\openjfx-20.0.1_windows-x64_bin-jmods\javafx-jmods-20.0.1" \ --module-path "C:\path\to\controlsfx-11.1.2.jar" \ --win-console \ --dest C:\outputs \ --main-jar tests-1.0-SNAPSHOT.jar \ --main-class tests.App
-
验证打包结果
安装生成的 .exe 后，进入安装目录下的 runtime\bin，运行：java --list-modules | findstr "controls"
应看到：
javafx.controls@20.0.1 org.controlsfx.controls@11.1.2
⚠️ 注意事项与替代方案
- 避免自动模块陷阱：若使用旧版 ControlsFX（如 ≤ 8.x）或非模块化 JAR，jar --describe-module 会返回 No module descriptor found. Derived automatic module.。此时它无法通过 --add-modules 加载，必须改用 classpath 方式：将 JAR 复制到 --input 目录下（如 --input target/libs/controlsfx.jar），jpackage 会自动将其加入 app.classpath（检查生成的 {app}.cfg 文件确认）。
- Maven 项目推荐做法：在 pom.xml 中声明 ControlsFX 依赖，并配置 maven-dependency-plugin 将其复制到 target/lib/，再统一指定 --input target —— 这比手动管理路径更可靠。
- 模块冲突预防：确保 ControlsFX 版本与 JavaFX 主版本兼容（例如 JavaFX 20 + ControlsFX 11.x）。混合使用不匹配版本可能导致运行时 NoClassDefFoundError 或 IncompatibleClassChangeError。
掌握模块名识别与路径语义，是 jpackage 模块化打包的核心能力。一次验证、两次修正、三次验证，即可稳定集成 ControlsFX。
