三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Java应用部署：系统化排查“找不到或无法加载主类”错误

发布时间：2026/8/13 14:06:14 三亩地 编程学习日记
Java应用部署：系统化排查“找不到或无法加载主类”错误

1. 问题现象与核心痛点剖析

“错误：找不到或无法加载主类”，这行看似简单的Java命令行报错信息，背后可能隐藏着从打包、依赖到环境配置的一系列问题。对于刚接触Java应用部署的开发者，或者是在一个看似稳定的环境中突然遇到此问题的老手，这个错误都足以让人眉头一皱。它不像空指针异常那样直接指向代码逻辑，而是像一个模糊的“系统级”故障，让人一时不知从何下手。

这个问题的本质是Java虚拟机（JVM）在启动时，无法根据你提供的类路径（Classpath）和主类名（Main-Class）定位到那个包含public static void main(String[] args)方法的入口类。java -jar命令的运行逻辑是：JVM会首先读取JAR包内META-INF/MANIFEST.MF文件中的Main-Class属性，获取到全限定类名（如com.example.MyApp），然后在自己所能“看到”的所有类路径中去寻找这个类。一旦寻找失败，“找不到或无法加载主类”的错误就会抛出。因此，排查这个问题的核心思路，就是沿着“JAR包结构 -> MANIFEST.MF 配置 -> 类路径 -> JVM环境”这条链路，进行逐层递进的检查。无论是使用Maven、Gradle构建的Spring Boot应用，还是手动打包的普通Java程序，其排查逻辑都是相通的。

2. 问题根源的逐层排查框架

遇到这个问题，切忌盲目尝试。建立一个系统性的排查框架，能帮你快速定位问题所在。我们可以将问题根源分为四个层级：JAR包内部问题、命令行使用问题、环境与依赖问题，以及更深层次的类加载机制冲突。

2.1 第一层：JAR包本身与清单文件（MANIFEST.MF）

这是最直接、也最高频的问题发生层。java -jar命令严重依赖JAR包内的META-INF/MANIFEST.MF文件。

1. 检查MANIFEST.MF文件内容首先，你需要确认你的JAR包是否是一个“可执行JAR”。使用解压工具（如WinRAR、7-Zip）或命令行打开JAR包，查看META-INF/MANIFEST.MF文件。关键检查以下两行：

Main-Class: com.yourcompany.yourapp.Main Class-Path: .
  • Main-Class：这是必须项。其值必须是包含main方法的类的全限定名（包名.类名）。常见错误包括：
    • 写成了相对路径或文件名，如Main或com/yourcompany/yourapp/Main.class。
    • 类名拼写错误，大小写不匹配（在区分大小写的系统上）。
    • 打包后，实际的类文件路径与这里声明的全限定名无法对应。
  • Class-Path：此项定义了JVM在加载JAR包内类的同时，还应从哪些额外的JAR包或目录加载类。一个点.代表当前目录（即JAR包所在目录）。如果你的应用依赖了外部的第三方JAR（非Spring Boot那种Fat Jar），就需要在这里显式列出，用空格分隔。例如：lib/dependency1.jar lib/dependency2.jar。

实操心得：对于使用Mavenmaven-jar-plugin或 Gradlejar任务打出的普通JAR包，务必在配置中正确指定Main-Class。很多新手会忘记这一步，导致生成的JAR包根本没有Main-Class属性。

2. 验证JAR包结构确认MANIFEST.MF中的Main-Class后，需要验证类文件是否真的存在于JAR包中预期的位置。继续在解压工具中浏览，找到对应的.class文件路径。例如，对于Main-Class: com.example.App，你必须在JAR包内找到com/example/App.class这个文件。如果找不到，说明打包过程有问题，可能源代码未被正确编译包含，或者打包时目录结构设置错误。

3. 区分“可执行JAR”与“依赖JAR”这是Spring Boot开发者常踩的坑。Spring Boot的Maven/Gradle插件默认会生成两种JAR：

  • your-app-0.0.1-SNAPSHOT.jar：这是一个Fat Jar / Uber Jar，它使用一个特殊的org.springframework.boot.loader.JarLauncher作为Main-Class，并将所有依赖（包括Spring Boot自身）和你的应用类都打包进一个JAR内。你应该使用java -jar运行这个。
  • your-app-0.0.1-SNAPSHOT-plain.jar（或通过特定配置生成的原生JAR）：这通常是一个普通的JAR，只包含你编写的应用代码，不包含依赖。它的Main-Class是你自己定义的类（如com.example.Application）。如果你错误地尝试用java -jar运行这个普通JAR，而它的Class-Path又没有正确指向所有依赖库，就一定会报“找不到或无法加载主类”，因为JVM找不到Spring框架等依赖类。

排查技巧：快速判断一个JAR是否是Spring Boot Fat Jar，可以用jar tf your-app.jar | grep -E “(BOOT-INF|org/springframework/boot/loader)”命令（Linux/Mac）或在解压工具中查看是否存在BOOT-INF/classes和BOOT-INF/lib目录。Fat Jar的Main-Class通常是org.springframework.boot.loader.JarLauncher。

2.2 第二层：命令行参数与当前工作目录

即使JAR包本身没问题，错误的命令行使用方式也会触发此错误。

1. 使用-cp参数与-jar参数的互斥性java -jar命令是一个“一站式”命令，JVM会忽略命令行中通过-cp或-classpath指定的类路径，以及CLASSPATH环境变量，完全依赖JAR包内MANIFEST.MF文件中的Class-Path属性。这是一个关键陷阱。

  • 错误用法：java -cp “./lib/*” -jar myapp.jar。这里的-cp参数会被忽略。
  • 正确用法（对于非Fat Jar）：如果JAR包是普通的，且依赖外部的JAR，你有两种选择：
    • A. 依赖MANIFEST.MF：确保MANIFEST.MF中的Class-Path正确列出了所有依赖JAR的相对路径（相对于运行JAR的目录），然后直接java -jar myapp.jar。
    • B. 不使用-jar：将你的主JAR包也当作依赖之一，使用-cp指定所有类路径，并显式指定主类名：
      java -cp “myapp.jar:./lib/*” com.example.Main
      （Windows上用分号;替换冒号:）

2. 当前工作目录的影响MANIFEST.MF中的Class-Path是相对于运行java -jar命令时的当前目录的。如果你在Class-Path中写了lib/foo.jar，但运行时不是在JAR包所在目录，或者在子目录中运行，JVM自然找不到lib/foo.jar，从而导致主类的依赖类加载失败，间接引发“找不到主类”（因为主类可能依赖其他类，那些类先加载失败）。

注意事项：始终保持清晰的目录结构。一种最佳实践是，在包含主JAR包的目录下，建立一个固定的lib文件夹存放所有依赖，然后在MANIFEST.MF中配置Class-Path: lib/*.jar（注意，通配符*在MANIFEST.MF的Class-Path中是从Java 6开始支持的）。运行命令时，确保终端就在这个目录下。

2.3 第三层：Java环境与依赖冲突

当排除了JAR包和命令行的问题后，我们需要审视运行环境本身。

1. Java版本兼容性使用java -version确认你运行时使用的Java版本。如果你的应用是用Java 11编译的（比如使用了var局部变量类型推断），但尝试用Java 8来运行，JVM在解析类文件时可能遇到版本不兼容的问题，导致类加载失败。确保运行环境（JRE/JDK）的版本大于等于编译环境的版本。

2. 依赖缺失或冲突（针对非Fat Jar）对于普通JAR，即使MANIFEST.MF的Class-Path路径正确，如果指定的JAR文件缺失，或者JAR文件本身损坏，依赖类就无法加载。主类可能因为其依赖的某个基础类（如某个Apache Commons库的类）找不到而无法被成功加载。可以使用-verbose:class参数来观察类加载过程，但这会输出大量信息。

3. 系统类路径（CLASSPATH）干扰虽然java -jar会忽略-cp和CLASSPATH环境变量，但在某些极其特殊或配置混乱的环境中，可能存在一些底层干扰。作为一个排查步骤，可以尝试在一个全新的命令行窗口（确保没有自定义CLASSPATH）中运行，或者显式地设置一个空的类路径：java -cp ”” -jar myapp.jar（注意，-cp ””必须放在-jar之前）。

2.4 第四层：类加载器与安全策略等深层问题

这类问题相对少见，但一旦出现，排查难度较大。

1. 自定义类加载器的影响如果你的应用内部（或通过某个依赖）使用了自定义的类加载器，并且加载逻辑有缺陷，可能导致主类在“应该”被加载时，没有被正确的类加载器处理。这在一些复杂的框架应用或Web容器嵌入场景中可能出现。

2. 打包工具或插件BUG极少数情况下，可能是使用的构建工具（Maven/Gradle）的某个插件版本存在BUG，导致生成的MANIFEST.MF文件格式不正确（例如行结束符错误、未以空行结束）。MANIFEST.MF文件有严格的格式要求：每行不能超过72字节，最后必须以一个空行结束。你可以尝试用jar xf myapp.jar META-INF/MANIFEST.MF提取清单文件，然后用文本编辑器检查其格式。

3. 文件系统权限或字符编码在Linux/Unix系统下，确保JAR包及其内部文件有可读权限。另外，如果类名或包名包含了非ASCII字符（如中文），在编译、打包、运行过程中，如果字符编码不一致（如UTF-8 vs GBK），也可能导致类名匹配失败。

3. 系统性排查流程与实操命令

结合以上分析，我总结了一套从快到慢、由表及里的排查流程。你可以像查字典一样，按顺序执行这些步骤。

3.1 第一步：快速诊断与信息收集（1分钟）

  1. 确认JAR包类型：jar tf your-app.jar | head -20。快速查看内容，判断是Fat Jar（有BOOT-INF）还是普通JAR。
  2. 检查Java版本：java -version和javac -version（如果安装了JDK）对比。
  3. 检查运行命令：回顾你的命令行，确认没有错误地混合使用-cp和-jar。

3.2 第二步：深入检查JAR包内部（3-5分钟）

  1. 提取并检查MANIFEST.MF：

    # 提取清单文件到当前目录 jar xf your-app.jar META-INF/MANIFEST.MF # 查看内容 cat META-INF/MANIFEST.MF

    重点关注Main-Class和Class-Path。确保Main-Class的值没有多余空格或换行。

  2. 验证主类文件是否存在：

    # 假设 Main-Class 是 com.example.Main jar tf your-app.jar | grep “com/example/Main.class”

    如果找不到，说明打包有问题。

  3. （针对普通JAR）验证Class-Path中的依赖： 根据MANIFEST.MF中的Class-Path，逐一检查列出的JAR文件是否存在于运行目录的相对路径下。

3.3 第三步：环境与替代方案测试（2-3分钟）

  1. 使用-cp方式绕过-jar： 这是诊断MANIFEST.MF问题最有效的方法。将你的主JAR包作为类路径的一部分，并显式指定主类。

    # Linux/Mac java -cp “your-app.jar:./lib/*” com.example.Main # Windows java -cp “your-app.jar;./lib/*” com.example.Main
    • 如果这样能成功，那问题100%出在MANIFEST.MF文件（Main-Class写错或格式错误）或者-jar与Class-Path的配合上。
    • 如果这样也失败，并且报同样的错，那问题可能出在：① 你指定的主类名com.example.Main不对；②your-app.jar里确实没有这个类；③ 依赖缺失（即使用了./lib/*，可能还有别的依赖路径没加进来）。

  2. 简化环境测试： 在一个新的、干净的目录下，只放入你的JAR包和必要的依赖库，然后重新运行。排除其他项目文件或复杂目录结构的干扰。

3.4 第四步：高级诊断与日志分析

如果以上步骤均无效，就需要启用更详细的JVM日志。

  1. 启用详细类加载日志：

    java -verbose:class -jar your-app.jar 2>&1 | grep -i “load.*com/example/Main”

    观察输出中是否有尝试加载你的主类的记录，以及加载成功或失败的原因。大量的输出会显示所有加载的类，你可以将其重定向到文件慢慢分析。

  2. 检查JAR文件完整性：

    jar tvf your-app.jar > /dev/null && echo “JAR seems OK” || echo “JAR is corrupt”

    如果jar tvf命令报错，说明JAR包可能已损坏，需要重新构建或下载。

4. 常见构建工具场景下的问题与解决方案

不同的构建工具和项目类型，产生此问题的常见原因各有侧重。

4.1 Maven项目（非Spring Boot）

问题场景：使用mvn package生成了target/xxx.jar，直接运行java -jar报错。根因分析：默认的maven-jar-plugin不会在MANIFEST.MF中添加Main-Class和依赖的Class-Path。解决方案：在pom.xml中配置maven-jar-plugin。

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.3.0</version> <configuration> <archive> <manifest> <!-- 指定你的主类 --> <mainClass>com.yourcompany.yourapp.Main</mainClass> <!-- 添加依赖到Class-Path --> <addClasspath>true</addClasspath> <classpathPrefix>lib/</classpathPrefix> </manifest> </archive> </configuration> </plugin> <!-- 还需要maven-dependency-plugin将依赖拷贝到target/lib --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-dependency-plugin</artifactId> <executions> <execution> <id>copy-dependencies</id> <phase>package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${project.build.directory}/lib</outputDirectory> </configuration> </execution> </executions> </plugin> </plugins> </build>

配置后，执行mvn clean package，生成的JAR包将包含正确的清单文件，且所有依赖JAR会被复制到target/lib/下。运行时，确保在target目录下执行java -jar xxx.jar。

4.2 Spring Boot项目

问题场景1：运行java -jar报错，但IDE里能启动。排查：99%的情况是运行了错误的JAR。确保你运行的是target/目录下那个较大的Fat Jar（通常几十MB），而不是可能存在的plain.jar。检查文件名。

问题场景2：自定义了Main-Class。排查：Spring Boot Fat Jar的Main-Class必须是org.springframework.boot.loader.JarLauncher（或WarLauncher）。如果你在构建配置中错误地覆盖了它，会导致启动器失效。在pom.xml中，确保spring-boot-maven-plugin没有被错误配置mainClass（这个配置是用于repackage目标的，通常不需要手动改）。application的主类是通过@SpringBootApplication注解的类，它与JAR清单中的Main-Class是两个概念。

问题场景3：使用java -cp app.jar com.example.Application方式运行Spring Boot Fat Jar。结果：一定会失败。因为Spring Boot的特殊类加载机制（LaunchedURLClassLoader）需要通过它的JarLauncher来启动。必须使用java -jar。

4.3 Gradle项目

问题场景：使用gradle jar任务打出的JAR无法用java -jar运行。根因分析：和Maven默认情况类似，Gradle的jar任务不处理主类和依赖。解决方案：在build.gradle或build.gradle.kts中应用application插件，或手动配置jar任务的清单。

// 使用 application 插件，它会帮你配置主类和创建启动脚本 plugins { id ‘application’ } application { mainClass = ‘com.yourcompany.yourapp.Main’ } // 或者，手动配置 jar 任务的清单 jar { manifest { attributes ‘Main-Class’: ‘com.yourcompany.yourapp.Main’ attributes ‘Class-Path’: configurations.runtimeClasspath.files.collect { “lib/$it.name” }.join(‘ ‘) } } // 还需要一个任务将依赖拷贝到 lib 目录 task copyDependencies(type: Copy) { from configurations.runtimeClasspath into “$buildDir/libs/lib” } assemble.dependsOn copyDependencies

5. 疑难杂症与特殊案例记录

在实际开发和运维中，我还遇到过一些不那么直观的案例，它们扩展了我们对这个问题的理解边界。

案例一：文件系统大小写敏感性问题开发环境是Windows（大小写不敏感），生产环境是Linux（大小写敏感）。代码中主类定义为public class MainApp，但在MANIFEST.MF中写成了Main-Class: com.example.mainapp。在Windows上测试通过，部署到Linux后报“找不到或无法加载主类”。教训：始终保持清单文件中的类名与实际的类定义完全一致，包括大小写。

案例二：依赖JAR的嵌套依赖缺失一个普通JAR应用，MANIFEST.MF的Class-Path正确列出了lib/a.jar和lib/b.jar。但a.jar本身又依赖c.jar（但c.jar没有在Class-Path中）。在运行时，当主类调用到a.jar中某个需要c.jar的类时，会抛出NoClassDefFoundError，而这个错误有时会以“找不到或无法加载主类”的“上游”形式被捕获和报告，尤其是当类加载失败发生在静态初始化阶段时。排查方法：使用-verbose:class观察是哪个类加载失败，然后顺藤摸瓜找到缺失的传递性依赖。

案例三：JDK模块化（JPMS）的影响对于Java 9及以上版本，如果JAR包是一个模块化模块（包含了module-info.class），并且主类所在的包没有在模块描述符中exports出来，那么即使MANIFEST.MF配置正确，在非模块路径下使用java -jar也可能失败。因为-jar会启动一个“未命名模块”，它只能读取到自动模块或未命名模块中的包。解决方案：对于模块化应用，更推荐使用java -p <module-path> -m <module>/<mainclass>的方式启动。或者，确保主类所在的包被exports到至少unnamed模块。

案例四：杀毒软件或安全软件干扰在一些严格管控的企业环境中，安全软件可能会实时扫描或拦截JAR文件的读取、解压过程，导致JVM无法正常访问JAR包内的类文件，从而引发加载失败。这类问题通常没有规律，且错误信息可能不明确。可以尝试暂时禁用安全软件（在测试环境），或将JAR文件、运行目录添加到安全软件的白名单中。

遇到“错误：找不到或无法加载主类”，从JAR包清单这个最直接的线索入手，逐步向外排查环境与依赖，大部分问题都能在十分钟内定位。养成规范打包、清晰管理依赖的习惯，能从根本上避免此类问题。对于Spring Boot等现代框架，理解其打包原理和默认约定，更是避免踩坑的关键。当所有常规检查都无效时，别忘了还有-verbose:class这把利器，它能带你看到JVM眼中的类世界，往往能发现那些隐藏最深的问题线索。

编程学习 学习日记 实战经验
← 返回列表