本文详解在 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>）精确匹配引用端：

• 例如 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> 根节点内，版本与安装坐标完全一致：

Java Development Manual

Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设...

下载

<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 项目中引入自定义依赖的唯一确定性失败原因。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南