ClassNotFoundException表明JVM在classpath中未找到指定类，需依次检查类名拼写与包路径、编译输出目录是否加入classpath、第三方依赖JAR是否缺失或版本冲突、类加载器隔离问题，以及Java 9+模块路径配置是否正确。
如果您运行Java程序时遇到ClassNotFoundException，说明JVM在类路径（classpath）中未能定位到指定的类。以下是针对该异常的多种排查与修复方法：
一、检查类名拼写与包路径是否完全匹配
ClassNotFoundException常因类名大小写错误、包路径遗漏或斜杠/点号混淆导致。Java对类全限定名严格区分大小写，且必须与文件系统中的目录结构一致。
1、确认抛出异常时打印的完整类名，例如java.lang.ClassNotFoundException: com.example.MyService。
2、在项目源码或编译输出目录中，查找是否存在对应路径com/example/MyService.class。
立即学习“Java免费学习笔记（深入）”；
3、核对import语句、反射调用（如Class.forName("...")）中的字符串，确保无多余空格、无半角/全角字符混用、无误写的下划线或连字符。
二、验证编译输出目录是否已加入classpath
JVM仅从classpath指定的路径中加载类，若.class文件未被包含，则必然触发该异常。需确认当前运行环境实际使用的classpath是否覆盖了目标类所在目录。
1、在命令行运行Java时，使用-cp或-classpath参数显式指定路径，例如：java -cp "bin:lib/*" com.example.Main。
2、若使用IDE（如IntelliJ IDEA或Eclipse），检查模块的Output path和Dependencies配置，确保编译后的class文件目录（如out/production或target/classes）已标记为“Sources”或“Compiled output”。
3、在代码中添加调试语句：System.out.println(System.getProperty("java.class.path"));，运行后查看输出的实际classpath值。
三、排查依赖JAR包是否缺失或版本不兼容
当异常类属于第三方库（如org.apache.commons.codec.binary.Base64），则问题通常源于JAR包未引入、路径错误或存在多个冲突版本。
1、检查项目构建配置文件：Maven用户确认pom.xml中存在对应<dependency>且<scope>非provided或test。
2、执行mvn dependency:tree -Dincludes=groupId:artifactId（替换为实际坐标）验证该依赖是否被成功解析并下载至本地仓库。
3、运行时检查JAR包内容：使用jar -tf your-dependency.jar | grep -i "Base64.class"，确认目标类确实存在于该JAR中；同时确保运行时classpath中没有同名但不含该类的旧版JAR（如commons-codec-1.3.jar不包含Base64类，而1.10+才支持）。
四、检查类加载器隔离机制引发的可见性问题
在Web容器（Tomcat）、OSGi或自定义ClassLoader环境中，不同类加载器构成委托链，可能导致某个类对当前加载器不可见。
1、在发生异常的位置，打印当前线程上下文类加载器：System.out.println(Thread.currentThread().getContextClassLoader());。
2、对比该加载器的getResource("com/example/MyService.class")返回值是否为null；若为null，说明该类加载器无法访问该资源。
3、对于Web应用，确认类文件位于WEB-INF/classes而非WEB-INF/lib外的任意位置；若需跨模块共享类，应将JAR放入WEB-INF/lib或容器共享目录（如Tomcat的lib/），并确保未启用antiJARLocking或clearReferences等可能干扰类加载的行为。
五、验证模块路径（Java 9+）与自动模块兼容性
在Java 9及以上版本中，若使用--module-path启动，传统classpath机制可能被绕过，未声明依赖的模块将无法访问其他模块中的类。
1、检查运行命令是否混用--module-path与-cp，例如：java --module-path mods -cp lib/* MyApp会导致lib/*中的JAR以自动模块方式加载，但默认不导出所有包。
2、使用jdeps --list-deps your-app.jar分析依赖图谱，确认缺失类所属模块是否出现在输出中。
3、若目标类在自动模块JAR中，需在java命令中添加--add-exports 模块名/包名=ALL-UNNAMED，例如：--add-exports java.base/sun.nio.ch=ALL-UNNAMED；同时确保模块描述符（module-info.java）中已通过requires声明所需模块，或JAR本身包含合法的META-INF/MANIFEST.MF模块定义。
