本文详解在 Java 9+ 模块系统（JPMS）下，JavaFX Maven 项目因未在 module-info.java 中声明 requires 而导致 NoClassDefFoundError 的根本原因，并提供从依赖声明、模块配置到运行验证的完整解决方案。
本文详解在 java 9+ 模块系统（jpms）下，javafx maven 项目因未在 `module-info.java` 中声明 `requires` 而导致 `noclassdeffounderror` 的根本原因，并提供从依赖声明、模块配置到运行验证的完整解决方案。
在基于模块化的 JavaFX Maven 项目中，仅在 pom.xml 中添加自定义依赖（如 <dependency><groupid>com</groupid><artifactid>mavenproject1</artifactid><version>2.0-SNAPSHOT</version></dependency>）是远远不够的。即使 Maven 成功下载并将其加入 classpath，若未在模块描述符 src/main/java/module-info.java 中显式声明对该模块的依赖，Java 运行时将严格遵循 JPMS 的强封装规则——该依赖中的类对主模块完全不可见，从而在运行时抛出 java.lang.NoClassDefFoundError 或 ClassNotFoundException。
✅ 正确集成需严格遵循以下三步闭环流程：
一、确保被依赖模块已正确构建并安装到本地仓库
在自定义模块（如 mavenproject1）根目录执行：
mvn clean install
验证目标 JAR 已生成于 target/ 目录，且其坐标（<groupid>.<artifactid>:<version></version></artifactid></groupid>）精确匹配引用端：
立即学习“Java免费学习笔记（深入）”；
Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设...
- 例如
com.mavenproject1:2.0-SNAPSHOT→ 本地仓库路径应为~/.m2/repository/com/mavenproject1/2.0-SNAPSHOT/ - 注意：
<artifactid></artifactid>默认转为模块名的后半段（小写、点号保留），即com.mavenproject1是标准模块名，非com.mavenproject1-2.0-SNAPSHOT或其他变体。
二、客户端项目 pom.xml 中声明 Maven 依赖（基础但非充分）
确保 <dependency></dependency> 块位于 <dependencies></dependencies> 根节点内，版本与安装坐标完全一致：
<dependency>
<groupId>com</groupId>
<artifactId>mavenproject1</artifactId>
<version>2.0-SNAPSHOT</version>
</dependency>三、【核心】在 module-info.java 中显式声明 requires（JPMS 强制要求）
这是绝大多数开发者遗漏的关键步骤。JavaFX 官方 archetype（如 Gluon 或 OpenJFX）默认启用模块化，因此必须在 src/main/java/module-info.java 中声明：
module com.mycompany.testfx { // ← 主模块名，通常为 groupId.artifactId
requires javafx.controls;
requires javafx.fxml;
requires com.mavenproject1; // ✅ 关键！模块名 = groupId.artifactId（小写、点号保留）
opens com.mycompany.testfx to javafx.fxml;
exports com.mycompany.testfx;
}⚠️ 模块命名规范：
- 若
pom.xml中<groupid>com.example</groupid>且<artifactid>utils</artifactid>，则模块名为com.example.utils； - 若
<groupid>com</groupid>+<artifactid>mavenproject1</artifactid>→ 模块名即为com.mavenproject1； -
不可使用
-、_或版本号，且大小写敏感。
补充：IDE 集成与验证建议
-
Eclipse / IDEA 用户：修改
pom.xml后务必执行 Maven → Update Project（Eclipse）或 Reload project（IntelliJ），确保 IDE 重新解析模块图； -
编译与运行命令：
mvn compile # 编译源码（含 module-info.java） mvn javafx:run # 启动应用（需配置好 javafx-maven-plugin 的 mainClass）
-
调试技巧：若仍报错，可运行
java --list-modules | grep mavenproject1验证模块是否被 JVM 加载；也可在module-info.java中临时添加requires static com.mavenproject1;（仅用于编译期检查，不推荐生产环境使用）。
? 总结：Maven 管理的是 类路径依赖，而 JPMS 管理的是 模块可见性。二者必须协同工作——
pom.xml解决“jar 是否存在”，module-info.java解决“类是否可访问”。忽略后者，即在模块化 JavaFX 项目中引入自定义依赖的唯一确定性失败原因。
