企业官网建设流程全解析

简介：面向Java开发者，这是一份针对IDEA中打包可执行jar时提示“找不到或无法加载主类 main”问题的PDF技术笔记。内容围绕Maven项目配置与IDEA图形化构建两条路径展开，重点讲解maven-jar-plugin中mainClass的正确填写方式、addClasspath对依赖引入的作用，并补充了Windows下CLASSPATH环境变量导致类加载失败的排查思路。资源为1个PDF文件，大小仅258KB，适合在IDEA中遇到打包困境、希望快速定位主类加载异常的初中级开发者查阅。目前已有20877人学习下载，说明该问题在Java日常开发中较为常见。通过这份笔记，读者可以掌握打包前manifest配置的关键细节，理解“找不到或无法加载主类”的底层原因，从而减少在命令行运行jar时的报错次数，提升交付效率。

1. IDEA打包jar：先弄清“找不到或无法加载主类 main”到底是谁在拦路

IDEA打包jar时，最让人头疼的报错之一就是“找不到或无法加载主类 main”。这个报错出现的时候，你的代码往往已经编译通过了，问题根本不在代码逻辑上。Java运行jar时，并不是按文件名找入口，而是先打开jar包里的META-INF/MANIFEST.MF文件，读到Main-Class配置，再去这个类里找public static void main(String[] args)方法。这个链路上任何一个环节对不上头，都会抛出那句让人反复怀疑人生的“找不到或无法加载主类”。

我处理这个问题的经验是：别急着改代码，先分清楚是哪一层的锅——是Manifest里没写主类，还是主类路径写错，又或者是运行环境里的CLASSPATH在捣乱。解决方案也基本固定：Maven方式重新打包、IDEA Artifacts方式兜底、最后清掉CLASSPATH这类历史包袱。这篇笔记适合两类人：一类是刚从“在IDE里点运行”过渡到“命令行交付jar”的新手，另一类是在Maven项目里被缺依赖、缺主类反复折腾的熟手。

2. Maven方式重新打包：maven-jar-plugin的配置边界与依赖处理

2.1 为什么建议你先走Maven而不是IDEA的Artifacts

如果你的项目已经用Maven管理，我会先推荐Maven方式而不是IDEA的Artifacts。原因很简单：mvn clean package这一段命令在命令行和CI环境里行为完全一致，打出来的jar不会因为你换了一台电脑、换了一个IDEA版本就改变结构。IDEA的Artifacts当然也能用，但它把输出目录、依赖配置都存在IDE的工程配置里，换个人打开项目，往往还得重新配一遍。

另一个原因是理解maven-jar-plugin的职责边界。这个插件只做一件事：把编译后的class按Maven坐标整理成jar，并且在Manifest里写入Main-Class。它不会把第三方依赖合并到jar里。很多人在这一层把期望放错了：配置了maven-jar-plugin，运行时却报NoClassDefFoundError，于是以为插件坏了，实际上是你没告诉它依赖怎么处理。先把这个边界搞清楚，后面的配置看着就不迷糊了。

2.2 配置pom.xml：mainClass路径从src/main/java下开始算

先说配置本身。原方案在pom.xml的<build>节点里加了maven-jar-plugin，关键片段是这样的：

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.0.2</version> <configuration> <archive> <manifest> <addClasspath>true</addClasspath> <mainClass>Main</mainClass> </manifest> </archive> </configuration> </plugin> </plugins> </build>

这段配置里最容易被坑的就是<mainClass>。它填的是主类的全限定名，而且这个路径是从src/main/java目录开始算的。如果你的入口类在src/main/java/Main.java，也就是默认包下，写Main就行；如果你的入口类在src/main/java/com/example/App.java，这里必须写com.example.App。很多人打包报错，就是因为类有包名，却只填了一个缩写的类名。

注意报错原文里的那个“main”，Java运行时是把“main”当作一个类名在找，不是方法名。如果你在Manifest里把Main-Class写成了小写main，运行时就会去找一个叫main的类，那当然找不到。另外，<addClasspath>true</addClasspath>的作用是在Manifest里生成Class-Path属性，把依赖的jar路径列出来。它只是“声明”，并不会把依赖jar复制到任何地方。如果你习惯把依赖放在jar同级的lib目录，还需要配合classpathPrefix参数，我一般会写<classpathPrefix>lib/</classpathPrefix>，这样Class-Path里就会出现lib/xxx.jar的形式。

2.3 三步做一次干净的Clean & Package

配置改好之后，真正打包不要直接点IDEA里的运行按钮，回到终端执行这两步：

mvn clean package -DskipTests java -jar target/项目jar包名.jar

第一步里的clean非常重要。它的作用是清空target目录，把旧的class和旧的jar全部删掉。很多“改了代码跑出来还是旧行为”的奇怪问题，根源就是target目录里残留了旧class，package阶段没有重新编译，直接把旧的产物打了进去。加上clean之后，整个构建过程从零开始，行为才可预期。

-DskipTests是跳过测试，只打包不跑测试用例，能省不少时间。如果你的项目里测试类本身有问题，比如某个测试代码引用了还不存在的资源，不跳过测试会直接卡在测试阶段，连jar都打不出来。第二步的java -jar是最终验收，如果这一步报“找不到或无法加载主类”，先别急着怀疑配置，用下面的命令看一眼Manifest里的实际内容：

unzip -p target/项目jar包名.jar META-INF/MANIFEST.MF

重点看Main-Class这一行，它输出的类名和你pom里写的是不是完全一致。我见过的情况里，有一部分是IDEA或者某些构建工具在中间环节改写了Manifest，还有一部分是类被重命名之后pom没同步更新。

2.4 依赖没打进去时：用maven-shade-plugin打出fat jar

maven-jar-plugin不会把第三方依赖并进jar，所以当你运行java -jar时，常见的报错有两种：一种是“找不到或无法加载主类”，另一种是“NoClassDefFoundError”。前者是Manifest的问题，后者是依赖缺失的问题。依赖缺失时，常见做法是给pom补一个maven-shade-plugin，把依赖直接并进一个可执行的fat jar。

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> <configuration> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>Main</mainClass> </transformer> </transformers> </configuration> </execution> </executions> </plugin>

版本号这里没写死，以你本地Maven仓库能拉到为准，我这边Maven 3.8环境下用3.2.x系列是正常的。配置的要点在于：<phase>绑定到package阶段，<goal>是shade，<transformer>用ManifestResourceTransformer来写Main-Class。shade插件会把依赖jar解压，然后把里面的class逐个合并进最终的jar，运行的时候就相当于自带依赖。

这里有个容易翻车的细节：如果你的依赖里有带数字签名的jar，合并之后可能会报“Invalid signature file digest”。原因是签名文件META-INF/*.SF被合并后对不上原来的内容。解决方法是加一个filters配置，把这些签名文件排除掉。我当时排查这个问题花了不少时间，最后才意识到是依赖本身带签名，不是shade插件坏了。

3. IDEA Artifacts方式打包：Project Structure里的三个关键字段

3.1 Artifacts配置流程与Main Class的选择

不是所有项目都愿意为了打包去折腾pom。快速交付一个内部用的命令行小工具时，直接用IDEA的Artifacts功能更省事。操作入口在File → Project Structure → Artifacts，点+号选JAR，然后选From modules with dependencies。

这一步对话框里最关键的就是Main Class。很多人习惯手敲类名，IDEA怎么提示都不看，结果打出来的Manifest路径是错的。正确做法是点右边的选择按钮，从项目类列表里直接选。选完之后IDEA会写入全限定名，比如com.example.Main，而不是一个光秃秃的Main。

之所以强调这一步，是因为“找不到或无法加载主类”在Artifacts方式下的第一原因，就是Main Class填了缩写类名，而类实际在某个包结构下。IDEA在选择器里会把全限定名填进去，手敲就容易漏包名。另一个容易被忽略的地方是模块选择。如果你的项目是多模块，对话框最上面的Module要选到真正包含主类的那一个模块，选错模块会直接导致Artifacts里根本看不到主类。

3.2 Output Layout里的依赖处理

Artifacts配置界面的下半部分是Output Layout，这里决定了最终jar的形态。当你选择From modules with dependencies时，IDEA会默认把编译输出和所有依赖列在这个区域里，同时给你两个选项来处理依赖：

• copy to the output directory and link via manifest：把依赖jar复制到最终产物旁边的lib目录，Manifest里通过Class-Path引用。
• extract to the output directory：把依赖jar里的class解压出来，直接合并到最终jar里，打成fat jar。

选择第一种时，你交付的文件就不止一个jar，还得带上旁边那个lib目录。只拷走jar文件是不行的，换一台机器就报NoClassDefFoundError。选择第二种时，最终产物是一个独立jar，方便分发。我一般做内部工具都会选第二种，省去带lib目录的麻烦。

这里有一个反直觉的坑：Output Layout里META-INF这一项不要手动删。有些人在调整输出目录结构时觉得META-INF碍眼，把它移除重新创建，结果IDEA就没地方写Main-Class属性了。打包确实能成功，但运行时就是找不到主类。我一直的做法是保持IDEA自动生成的META-INF不动，需要调整的是它下面Entry的依赖归类。

3.3 Build Artifacts的Build与Rebuild区别

配置完成后，通过Build → Build Artifacts构建。但这里有个需要说清楚的区别：Build是增量构建，只重新处理变化的部分；Rebuild是先把Artifacts的输出目录整个清空，再从编译产物重新组装。

如果你改了代码，然后直接点Build，有一定概率打出来的还是旧class。原因是IDEA的增量构建没能正确识别到所有变化的class，尤其是当你改了某个类的包名或者删除了某个类时，旧的class文件可能还残留在输出目录里。这种情况下，点Rebuild基本能解决。

另外要理解IDEA的Run按钮和jar运行环境的差异。你在IDEA里点Run，用的是模块的classpath，依赖由IDEA自己组织；而java -jar用的是jar包Manifest里的Class-Path和jar内部结构。“IDEA里能跑，java -jar跑不起来”是非常正常的事情，不代表代码有问题。所以用IDEA方式打完包，第三步必须是回到终端，用java -jar out/artifacts/项目名_jar/项目名.jar跑一次，才能算真正验证通过。

4. 避坑：CLASSPATH干扰与四个常见运行失败场景

4.1 编译已通过、运行却说找不到类：CLASSPATH的干扰

现象：用javac能编译成功，用java运行时报“找不到或无法加载主类”，或者class文件就在当前目录，却告诉你找不到类。在IDE里启动又一切正常。

原因：Windows环境变量CLASSPATH被之前某个项目或者某款软件改过，里面指向了其他目录下的旧版本jar或旧的class目录。Java运行时加载类时，会按照CLASSPATH里配置的路径去找，如果环境变量里配置了大量无关路径，可能绕过了当前目录,把你自己的主类给漏掉了。

解决：先在cmd里执行echo %CLASSPATH%看当前值。原方案里提到的做法是直接删除这个环境变量，我实际操作时建议更稳妥一点：先把原值复制到一份txt里保存，再删除，万一后续某个老项目还需要旧配置还能还原。删除之后重新打开一个cmd窗口再跑java -jar。JDK 9之后的版本对CLASSPATH依赖已经很低，模块化之后Java运行时可以从jar的Manifest直接定位主类，这个历史配置在绝大多数新项目里属于纯干扰项，清掉是安全的。

4.2 双击jar没反应：控制台异常才是第一线索

现象：jar包双击运行，窗口一闪而过，或者完全没有任何反应。有人以为是打包成功了但程序本身有问题，实际上连启动都没完成。

原因：双击jar时Windows用的是javaw进程，这个进程不绑定控制台，所以System.out和异常堆栈都不会显示。任何启动期错误都被吞掉了，看起来就像“没反应”。

解决：不要双击，打开cmd，先cd /d到jar所在目录，再执行java -jar 你的jar.jar。这时候异常会完整打印出来，看第一个异常的类型就能判断方向：如果报“找不到或无法加载主类 xxx”，优先检查Manifest里的Main-Class；如果报NoClassDefFoundError，优先检查依赖没打进去；如果报UnsupportedClassVersionError，说明编译JDK版本比运行JDK高，程序在低版本JDK上跑不起来。这个习惯养成之后，每次遇到这种问题我都先开终端，不在双击上浪费时间。

4.3 改了代码还是旧行为：强制走一次Clean/Rebuild

现象：改了代码，重新打包，跑出来还是旧功能。最典型的是新加的一个功能没出现在程序里，但单独编译新写的类又能通过。

原因：Maven方式下，target目录里的旧class没有清掉，package阶段只编译变化的源码，由于某个类依赖关系没有被正确识别，旧class被当成最新产物打进了jar。IDEA Artifacts方式下同理，Build是增量构建，Artifacts输出目录里的旧文件可能残留。

解决：Maven方式执行mvn clean package，不要只执行mvn package。IDEA方式用Build → Rebuild Artifacts，在输出目录结构异常时，直接手动删除out/artifacts目录再重新构建。我自己现在养成的习惯是任何正式打包都从clean开始，宁可多花几秒重新编译，也不赌增量构建的识别能力。

4.4 换机器跑不起来：JDK版本不一致与Manifest损坏

现象：自己机器上运行正常，把jar拷给同事或者放到服务器上，报“找不到或无法加载主类”或者“UnsupportedClassVersionError”。

原因：第一种情况是编译环境JDK版本高于运行环境JDK版本，class文件格式对低版本JDK不可见。第二种情况是jar被普通zip工具解压重打包过，Manifest文件末尾缺少换行，或者文件顺序被改写，导致Java解析Manifest失败。

解决：在pom.xml里明确设置maven.compiler.source和maven.compiler.target，让编译产物格式对目标运行环境可见。比如目标机器是JDK 8，就都设成1.8。重打jar时不要用zip工具解压再压缩，用jar命令或者IDEA/Maven重新构建。按这个原则处理后，换机运行的问题基本消失，“找不到主类”大多数是交付时只拷了fat jar却没有确认依赖真的在里面。

5. 验证五步法：把Main-Class和依赖问题拦在交付前

打包完成之后，我都会强制走一遍下面五个验证步骤，一套流程走下来，至少能把“找不到或无法加载主类 main”这个级别的问题挡在交付之前。

第一步，先跑一次原始命令确认报错可复现：java -jar your.jar。能稳定复现其实是好事，说明问题不涉及玄学，就是某个配置对不上。

第二步，直接看Manifest的真相：

unzip -p your.jar META-INF/MANIFEST.MF

重点检查Main-Class那一行和Class-Path（如果配置了addClasspath）。很多所谓“打包后找不到主类”，在这一步就能直接定位——Main-Class根本没写进去，或者写成了不带包名的缩写。

第三步，核对jar内部结构和Manifest是否一致：

jar tf your.jar | findstr "Main"

Windows下用findstr，Linux/macOS下把findstr "Main"换成grep Main。这一步确认Main.class在jar里的实际包路径，要和Main-Class里写的路径完全对应。之前遇到过一个情况：Manifest写的是com.example.Main，但jar里class的路径是com/example/Main.class，目录结构没问题却仍然报错，后来发现Manifest末尾缺了一个换行符，这是常见的格式问题。

第四步，项目有第三方依赖时，验证依赖有没有真正进包：

jar tf your.jar | findstr "net/dongliu"

以原方案里引用的net.dongliu:requests为例，如果jar里能列出net/dongliu/requests/...这类class文件，说明依赖已经合并进fat jar。如果列表为空，说明这个jar是thin jar，依赖还停留在外部，运行时自然会缺类。

第五步，最后检查一遍环境变量：

echo %CLASSPATH%

输出非空时，先把内容保存下来，再临时清空后重跑一次java -jar。如果清空后恢复正常，那这个项目往后就不需要CLASSPATH环境变量，让JAVA_HOME和jar本身负责类路径即可。

这套验证流程走完，大部分问题其实在第二步、第三步就已经暴露了。从那以后，我每次交付jar之前都强制过一遍这五步，先看Manifest再看class结构，最后才让程序跑起来，同事那边因为“找不到主类”找过来的次数明显少了很多。希望帮到你。

本文还有配套的精品资源，点击获取