ClassNotFoundException表示JVM运行时找不到指定类，常见于反射、动态加载等场景；核心原因是类路径缺失或ClassLoader隔离，需检查打包内容、依赖范围、类加载器委托及混淆/模块化配置。
ClassNotFoundException到底意味着什么
它不是代码写错了，而是 JVM 在运行时根本找不到你声明要加载的那个类。常见于 Class.forName()、ClassLoader.loadClass() 或反射调用场景，也常在动态加载插件、JDBC 驱动注册、Spring Bean 初始化失败时冒出来。
关键判断点：编译能过，运行时报错；错误信息里明确包含 java.lang.ClassNotFoundException: xxx.xxx.XxxClass；堆栈顶部通常指向类加载动作本身，而非你的业务逻辑深处。
检查 classpath 和依赖是否真正生效
这是 80% 的真实原因。Maven/Gradle 声明了依赖，不代表它进了最终的运行 classpath —— 尤其在打包成 jar 或部署到容器时容易断链。
- 用
jar -tf your-app.jar | grep XxxClass确认目标类是否真的被打包进去了 - 如果是 Web 应用，检查
WEB-INF/lib/下是否有对应 jar；Tomcat 启动日志里搜Deploying web application看有没有跳过某些 jar - Maven 多模块项目中，确认
dependency的scope不是provided或test，否则运行时不会传递 - IDE 运行配置里，检查
Run Configuration → Classpath是否包含了所有 module output 和依赖 jar
ClassLoader 层级和委托机制引发的“看不见”问题
同一个类名，不同 ClassLoader 加载出来的实例是不兼容的。当你手动调用 Thread.currentThread().getContextClassLoader().loadClass("Xxx")，而该 ClassLoader 没有被正确设置（比如在 Servlet 容器或 OSGi 环境中），就会抛出这个异常，哪怕类物理存在。
立即学习“Java免费学习笔记（深入）”；
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
典型场景：
- 使用
URLClassLoader动态加载外部 jar，但没把父 ClassLoader 显式传入构造函数，导致无法访问应用本身的类 - Spring Boot fat jar 中，
LaunchedURLClassLoader默认不代理到系统类加载器，若你硬编码用了ClassLoader.getSystemClassLoader()去 load，就会失败 - JDBC 4.0+ 要求驱动类自动注册，但如果你删了
META-INF/services/java.sql.Driver文件，或用了错误的 ClassLoader，DriverManager就找不到实现类
URLClassLoader child = new URLClassLoader(new URL[]{new URL("file:/path/to/plugin.jar")},
Thread.currentThread().getContextClassLoader()); // ← 关键：传入 parent
Class<?> clazz = child.loadClass("com.example.PluginService");混淆、模块化（Java 9+）和签名验证带来的隐性拦截
ProGuard / R8 混淆后类名变了，但反射代码里还写原名，自然找不到；Java 9+ 的模块系统默认禁止跨模块反射访问，即使类存在也会被 ClassNotFoundException 掩盖真实权限问题；JAR 签名损坏也会让类加载器静默拒绝加载。
排查建议：
- 混淆后检查 mapping.txt，确认目标类是否被保留（
-keep class com.example.** { *; }） - 模块化项目中，在
module-info.java里加opens com.example.package to java.base;（如需反射访问） - 用
jarsigner -verify -verbose your.jar查看签名状态，失败时会提示 “signature failure”
这类问题往往没有明显线索，得从构建产物反向验证，而不是只盯着异常堆栈。
