模块未找到异常是JPMS模块解析阶段问题，需检查模块物理存在性、requires精确匹配、模块路径配置、exports包导出及多版本JAR兼容性。
模块未找到异常（如 module not found、require failed: module X not found）本质是 JPMS 在模块解析阶段无法定位目标模块，不是运行时报错，而是启动时静默跳过或直接失败。排查重点不在代码逻辑，而在模块声明、路径配置和加载顺序。
确认模块是否真实存在于模块路径中
Java 不会主动报“找不到模块”，而是跳过未解析的 requires。第一步必须验证模块物理存在：
- 检查
--module-path指定路径下是否有对应 JAR 或目录，且文件名/目录名与module-info.java中声明的模块名**完全一致**（大小写、点号、下划线都不能差） - 运行
java --list-modules | grep -i "目标模块名"，看是否出现在已解析模块列表中 - 加启动参数
--show-module-resolution，观察控制台输出中是否有require failed: module 目标模块名 not found这类提示
核对 requires 声明是否精确匹配
requires 必须与提供方模块的 module xxx.yyy 声明逐字符一致，且不能带版本号：
- 错误示例：
requires com.example.util@1.2;（JPMS 不支持在requires中写版本） - 错误示例：
requires com.example.util;，但对方实际声明为module com.example.util.core { } - 若使用多版本 JAR（MRJAR），确保运行 JDK 版本 ≥ 模块声明的最低版本，否则模块可能被忽略
区分模块路径与类路径的混用问题
一旦同时用了 --module-path 和 -cp（或 --class-path），JVM 就把类路径上的内容视为“未命名模块”，具名模块无法通过 requires 依赖它：
立即学习“Java免费学习笔记（深入）”；
- 执行
java --describe-module 目标模块名：若返回Module xxx not found，说明它根本不在模块路径上；若返回no module descriptor，说明它是自动模块，模块名取自 JAR 文件名（不含扩展名），需严格对应 - 旧版 Spring Boot 打包方式默认走 classpath，此时
requires无效，应改用requires static+ 反射，或迁移到纯模块化部署
验证 exports 是否覆盖到消费方需要的包
exports 是按包控制的，不递归包含子包：
- 若提供方只写
exports com.example.util;，则com.example.util.helper中的类对外不可见，需额外声明exports com.example.util.helper; - 消费方能 import 的前提是：自己
requires了该模块，且该模块exports了对应包；可用javap --module 模块名 --show-module查其导出列表
