Java 17+模块化项目必须显式声明module-info.java，否则触发模块校验导致NoClassDefFoundError等错误；需正确放置路径、配置模块名、声明依赖与导出，并使用--module-path启动。
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: ...——这往往不是类没编译，而是模块未导出包、未声明依赖、或主类所在包未被
exports。
-
module-info.java必须放在源码根路径（如src/main/java/module-info.java），不能放在子包里 - 如果用 Maven，需确认
pom.xml中的<packaging>jar</packaging>且未启用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。
立即学习“Java免费学习笔记（深入）”；
正确做法：
- 模块名全小写、仅含 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 都是显式契约——少写一行，运行时就可能崩在最意想不到的地方。
