告别迷茫！深入理解 Java 中的 ClassNotFoundException 和 NoClassDefFoundError 及排查技巧

JavaEdge聊AI

已于 2025-05-13 22:16:50 修改

阅读量3.9k

点赞数 2

分类专栏： javase 文章标签： java

于 2020-01-23 14:16:48 首次发布

本文链接：https://blog.csdn.net/qq_33589510/article/details/104071182

版权

javase 专栏收录该内容

95 篇文章

订阅专栏

本文已收录在Github，关注我，紧跟本系列专栏文章，咱们下篇再续！

🚀 魔都架构师 | 全网30W技术追随者
🔧 大厂分布式系统/数据中台实战专家
🏆 主导交易系统百万级流量调优 & 车联网平台架构
🧠 AIGC应用开发先行者 | 区块链落地实践者
🌍 以技术驱动创新，我们的征途是改变世界！
👉 实战干货：编程严选网

0 前言

在 Java 开发中，ClassNotFoundException 和 NoClassDefFoundError 是两种常见的运行时问题，通常与类加载有关。虽然它们都表示某个所需的类无法被找到，但两者发生的阶段不同、原因也不一样。准确理解它们的区别对于排查问题非常关键。

1 特定环境中的类加载问题

数据库环境中加载 Java 类（如通过 Oracle 的 JVM 使用 loadjava 工具）。此时，若内存资源不足（如 Oracle 中的 SHARED_POOL_SIZE、JAVA_POOL_SIZE 设置太小），在类加载过程中可能出现“静默失败”，即没有明显报错，但类被错误地记录为“无效”或“损坏”。

之后，当应用程序试图使用这些加载失败的类时，就可能在运行时遇到 ClassNotFoundException 或 NoClassDefFoundError。

这种数据库相关场景下，推荐做法：

验证类是否被正确打包：确认目标类已经包含在部署到服务器的文件中
强制重新加载：使用 loadjava -force（Oracle 特有）强制替换已有的类定义，防止旧的损坏版本残留
提前解析依赖：使用 loadjava -resolve 选项，尝试在加载阶段解析依赖，避免运行时才发现依赖缺失
检查类状态：加载完成后，可以通过查询 Oracle 的 user_objects 来查看类的状态：
```
SELECT object_name, status, created, last_ddl_time
FROM user_objects
WHERE object_name = DBMS_JAVA.SHORTNAME('<your_fully_qualified_class_name>') -- 例如：'com/example/MyClass'
  AND object_type LIKE 'JAVA%';
```
STATUS 应为 VALID。如果加载期间出现内存或连接问题，建议先调整数据库配置（如增大内存池）后再重试。

虽然这个前言聚焦于数据库环境，但后续要讲的两个异常是通用的 Java 概念。

2 ClassNotFoundException

官方定义（Java SE 规范）：

当应用程序尝试通过类的字符串名称来加载类时（如通过以下方法）：

Class.forName
ClassLoader.findSystemClass
ClassLoader.loadClass

但找不到该类的定义时，会抛出该异常。示意图：ClassNotFoundException 栈轨迹

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

通俗解释：JVM 或某个类加载器通过全限定类名（如 "com.example.MyClass"）试图动态加载一个类时，没有在 classpath 或 module path 中找到对应的 .class 文件。

异常类型：java.lang.Exception（受检异常，必须捕获或声明抛出）

常见原因：

类名拼写错误：字符串写错了类名或包名。
缺失的 JAR 或类文件：包含该类的 JAR 文件未加入 classpath，或者单独的 .class 文件不存在。
classpath 配置错误：程序启动时未正确指定包含目标类的路径（例如 java -cp 或 -classpath 参数）。
上下文类加载器不正确：在一些复杂环境中（如应用服务器、插件系统），Thread.currentThread().getContextClassLoader() 可能无法访问目标类。
动态生成的类名无效：程序中构造了错误或不存在的类名。
模块系统问题（Java 9 及以上）：类所在的模块未声明为依赖，或者未导出类所在的包。

排查建议：

检查类名及包名是否正确拼写。
打印并检查当前 classpath，如：System.getProperty("java.class.path")。
确保所需 JAR 文件已正确部署并包含在 classpath 中（如 Web 应用应放在 WEB-INF/lib 中，或构建为 fat JAR/uber JAR）。
若使用 Maven/Gradle 等构建工具，确认依赖没有被错误地设置为 test 或 provided 范围。

3 NoClassDefFoundError

官方定义（Java SE 中对 Error 的定义）：

Error 是 Throwable 的子类，表示严重问题，合理的应用程序通常不应尝试捕获。

而 NoClassDefFoundError 的官方说明：

当 JVM 或类加载器在尝试加载某个类的定义时，未能找到该定义时会抛出。

这个类在编译当前执行代码时是存在的，但在运行时无法再找到或初始化该类。

通俗解释：编译时或先前运行时该类是存在的，但在真正“使用”它的时候（例如 new 实例、访问静态变量、或被另一个类引用时），JVM 无法将该类加载到内存中。

异常类型：java.lang.Error（非受检错误，通常表示严重问题，不建议应用程序主动处理）

常见原因：

运行时缺失类文件：编译时类是存在的，但运行时 JAR 或 .class 文件不在 classpath 中。
- 例如 Maven 中使用了 provided 范围（如 Servlet API），而运行环境未提供。

静态初始化失败：类中的 static {} 块或静态字段初始化时抛出异常，导致类初始化失败。之后再次访问该类时就会抛出 NoClassDefFoundError。

public class MyProblematicClass {
    private static String someValue = initializeOrDie();

    static {
        if (System.currentTimeMillis() % 2 == 0) {
            throw new RuntimeException("静态代码块失败！");
        }
    }

    private static String initializeOrDie() {
        if (true) throw new NullPointerException("静态字段初始化异常");
        return "初始化完成";
    }

    public void doSomething() {
        System.out.println("执行中...");
    }
}
// 调用：
// new MyProblematicClass(); // 有可能抛出 NoClassDefFoundError

依赖类缺失：主类本身存在，但它依赖的另一个类缺失，也会导致加载失败。
类文件损坏：.class 文件受损，JVM 无法正常解析。
本地库加载失败：如果该类依赖 JNI，本地库未能成功加载，也可能引发此错误。

排查建议：

认真检查异常栈，很多情况下错误前面已经抛出了实际的根本原因（特别是静态初始化失败的情况）。
确保编译期的依赖也被包含进运行环境，且版本一致。尤其注意 Maven 的 compile、runtime 与 provided 范围设置。
如果怀疑是静态初始化问题，检查类中的静态代码块与静态字段初始化代码，必要时加入日志或断点调试。
确保 .class 文件未损坏，尝试重新编译、打包、部署。

4 核心区别总结

对比点	`ClassNotFoundException`	`NoClassDefFoundError`
类型	`java.lang.Exception`（受检异常）	`java.lang.Error`（非受检错误）
发生时机	在调用 `Class.forName()`、`ClassLoader.loadClass()` 等方法动态加载类时	JVM 尝试使用一个类（例如 new、静态方法或字段访问）时
类文件状态	`.class` 文件根本找不到（通常是路径或配置错误）	`.class` 文件原本存在，但现在无法加载或初始化
常见原因	类名错误、JAR 缺失、classpath 配置问题	静态初始化失败、类运行时缺失、类依赖缺失或损坏
可恢复性	有时可以恢复，例如重试加载或提示用户更正路径	一般不可恢复，需修复配置或部署环境