Java模块化项目创建与运行教程

本文深入解析了Java 17+模块化项目从创建到运行的关键实践与常见陷阱，强调module-info.java不仅是可选配置，而是触发JVM严格模块校验的“开关”——哪怕内容为空也会导致NoClassDefFoundError、Module not found等隐蔽错误；文章系统梳理了模块声明的硬性规范（路径位置、命名约束、依赖声明）、IDE（IntelliJ/Eclipse）配置要点、启动参数（--module-path + --module替代-classpath）、第三方自动模块适配，以及通过--add-opens和精准exports/opens进行调试与修复的核心策略，直击开发者在迁移或新建JPMS项目时最易踩坑的实战盲区。

Java 17+ 项目必须显式声明 module-info.java

IDE（如 IntelliJ IDEA 或 Eclipse）新建 Java 项目时，若选择 “Java Platform Module System (JPMS)” 或 JDK 17+ 且勾选了 “Create module-info.java”，IDE 会自动生成一个空的 module-info.java 文件。但很多人忽略一点：只要项目根目录下存在 module-info.java，JVM 就按模块化方式加载——哪怕内容为空或只写 module myapp { }，也会触发模块系统校验。

常见错误现象：

Error: LinkageError occurred while loading main class com.example.Main
Caused by: java.lang.NoClassDefFoundError: ...

• module-info.java 必须放在源码根路径（如 src/main/java/module-info.java），不能放在子包里
• 如果用 Maven，需确认 pom.xml 中的 jar 且未启用 maven-jar-plugin 的自动模块名覆盖
• IntelliJ 中右键运行类时，若提示 “No module descriptor found”，说明 IDE 没识别到 module-info.java，检查是否在正确 source root 下，或 File → Project Structure → Modules → Sources 标记是否正确

IDEA 运行模块化项目前要检查 Run Configuration 的模块路径

非模块化项目用 -cp（类路径），模块化项目必须用 --module-path + --module 启动。IDEA 默认可能仍走传统 classpath 模式，导致 java.lang.module.FindException: Module not found。

实操建议：

• 打开 Run → Edit Configurations…，选中你的 Application 配置
• 在 Configuration 页签下，确认 Use classpath of module 已设为你的主模块（如 myapp.main）
• 展开 Environment → VM options，手动添加：

  --module-path out/production/myapp --module myapp/com.example.Main

  （路径和模块名按实际调整）
• 若用 Maven 构建，推荐改用 mvn compile exec:java -Dexec.mainClass="com.example.Main"，Maven 插件会自动处理模块路径

模块名不能含大写字母或连字符，且必须与文件路径一致

Java 规范要求模块名是有效的 Java 标识符，但实践中更严：IDE 和 jlink 工具常拒绝 MyApp 或 my-app 这类名称，报错如 error: module name does not conform to the grammar。

正确做法：

• 模块名全小写、仅含 ASCII 字母/数字/点号，例如：com.example.myapp（推荐）或 myapp
• module-info.java 中声明的模块名，必须与 src/main/java/ 下的包结构完全无关——它只是逻辑名，但必须和 javac 编译输出的 META-INF/MANIFEST.MF 中的 Automatic-Module-Name（如有）不冲突
• 如果依赖第三方 JAR（如 gson-2.10.1.jar），它没有 module-info.class，JVM 会生成自动模块名 com.google.gson；此时你的 requires 必须写 requires com.google.gson;，而不是 requires gson;

调试时看不到模块间访问错误？开启 JVM 的模块诊断

模块系统的很多问题（比如包未导出、服务未提供、反射受限）在运行时才暴露，但默认无明确提示。光看 IllegalAccessError 很难定位是哪个模块缺 opens 或 exports。

在 IDE 的 Run Configuration → VM options 中加入：

--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED

这只是临时绕过，真正修复需在 module-info.java 中精确声明：

• 需要反射访问内部类？用 opens com.example.internal to javafx.graphics;
• 想让其他模块使用你的 API 包？用 exports com.example.api;
• 依赖日志框架（如 SLF4J）？记得 requires org.slf4j;，并确保该 JAR 已在模块路径上

模块系统不是“开了就完事”的开关，每个 requires、exports、opens 都是显式契约——少写一行，运行时就可能崩在最意想不到的地方。

今天关于《Java模块化项目创建与运行教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！