LayerInstantiationException 是 Java 9+ 模块系统在构建 ModuleLayer 时因底层失败抛出的运行时异常，根本原因需通过 getCause() 查看，常见为 NoClassDefFoundError、ClassNotFoundException 或 InvalidModuleDescriptorException。
LayerInstantiationException 是什么错误
这个异常不是你代码写错了，而是 Java 9+ 模块系统在加载模块层（ModuleLayer）时，底层构造失败抛出的运行时异常。它本身不带具体原因，只是个“包装壳”，真正的问题藏在它的 getCause() 里——常见的是 NoClassDefFoundError、ClassNotFoundException 或 InvalidModuleDescriptorException。
你遇到它，基本意味着：用 ModuleLayer.defineModulesWithOneLoader() 或类似 API 构建模块层时，某个模块的依赖没找到、描述符语法错、或类路径/模块路径混用冲突了。
检查 module-info.class 和 requires 是否匹配
模块声明文件编译后生成的 module-info.class 必须和实际类路径上的依赖对得上。比如你在 module-info.java 里写了 requires javafx.controls;，但运行时没把 JavaFX 模块加进 --module-path，或者用了旧版 JDK（如 JDK 11+ 默认不含 JavaFX），就会在 define 阶段触发 LayerInstantiationException，根本原因其实是 FindException: Module javafx.controls not found。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 用
jar --file=your-module.jar --describe-module确认模块名、exports、requires 是否符合预期 - 确保所有
requires的模块都出现在--module-path中，且版本兼容（Java 9+ 模块不支持版本通配） - 如果模块是自己打的 jar，别漏掉
module-info.class—— Maven 打包时要启用maven-compiler-plugin的modulePath配置，否则它可能被当成自动模块
ClassLoader 传错导致模块解析失败
ModuleLayer.defineModulesWithOneLoader() 第二个参数要求传一个能加载这些模块类的 ClassLoader。常见错误是传了 ClassLoader.getSystemClassLoader()，但它默认不理解模块路径，只查 classpath；而你的模块 jar 在 --module-path 下，它根本找不到 module-info.class，于是抛出 LayerInstantiationException，根本原因是 IllegalArgumentException: No module descriptor found。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 不要硬写
ClassLoader.getSystemClassLoader()，改用ModuleLayer.boot().findLoader(yourModuleName)（如果你的模块已由启动层加载） - 如果是动态定义新层，推荐用
ClassLoader.of(...)（Java 15+）或自定义URLClassLoader并显式设置--module-path对应的URL[] - 调试时打印
layer.configuration().modules()，看模块是否真被解析出来；如果为空，说明ClassLoader根本没读到任何模块描述符
混合使用 classpath 和 module-path 的陷阱
Java 9+ 允许同时用 -cp 和 --module-path，但一旦模块里 requires 了一个传统 jar（即无 module-info.class 的 jar），它就变成自动模块（automatic module），名字来自 jar 文件名。这时候如果两个 jar 文件名相同（比如都叫 utils.jar），或者一个模块 requires utils，另一个又 requires utils@1.0，模块图构建会失败，LayerInstantiationException 的 cause 往往是 ResolutionException: Ambiguous module name。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 避免让自动模块参与核心依赖链；优先给第三方库打上模块描述符（哪怕只是空的
module-info.java） - 用
java --list-modules查看当前所有已知模块，确认自动模块名是否符合预期 - 启动命令中明确区分路径：
java --module-path mods --class-path libs -m myapp/mymain，别把模块 jar 放进-cp
最常被忽略的一点：这个异常永远不告诉你具体哪个模块出问题——必须调用 e.getCause().printStackTrace()，否则你只能看到一层空泛的 LayerInstantiationException，然后对着日志干瞪眼。
