为什么我的程序在 IDE 能跑，打包后就报错？—— classpath 初探
目录
一、什么是 classpath？
二、一个典型例子：读取配置文件失败
为什么？
三、图解：Maven 项目打包前后 classpath 的变化
🟢 开发阶段（IDE 运行）：
🔴 打包后（运行 jar）：
四、常见 classpath 问题 & 解决方案
五、如何打出一个“能跑”的 jar？
方法1：使用 Maven Shade Plugin（推荐给普通 Java 项目）
方法2：如果是 Spring Boot 项目
六、调试技巧：如何查看 jar 包里的内容？
结语
你是不是也经历过这种“玄学”时刻？
- 在 IntelliJ IDEA 里点一下 ▶️ Run，程序完美运行 ✅
- 但用
mvn package打成 jar 包，一运行就报错：
Exception in thread "main" java.lang.NoClassDefFoundError: com/example/ConfigLoader或者：
Could not find or load main class com.example.MainApp明明代码没改，为什么“打包后就不行了”？
罪魁祸首，很可能就是你没搞懂的——classpath（类路径）！
今天我们就用一篇短文，揭开 classpath 的神秘面纱，让你彻底告别“IDE 能跑，jar 不能跑”的尴尬！
一、什么是 classpath？
简单说：classpath 是 JVM 找 .class 文件（字节码）的“搜索路径”。
就像你在图书馆找书，得知道去哪个书架、哪一排。
JVM 也需要知道：你的Main.class、UserService.class、第三方 jar 包……到底放在哪里？
- 在 IDE 中：IDE 自动帮你配置好了 classpath（比如 src/main/java 编译后的输出目录）
- 在命令行运行 jar 时：JVM 只认jar 包内部结构和MANIFEST.MF 中的 Class-Path
一旦路径不对，JVM 就会说：“找不到这个类！”（NoClassDefFoundError / ClassNotFoundException）
二、一个典型例子：读取配置文件失败
假设你有如下代码：
// src/main/java/com/example/App.java public class App { public static void main(String[] args) throws IOException { InputStream is = App.class.getResourceAsStream("/config.properties"); if (is == null) { throw new RuntimeException("找不到 config.properties！"); } // ... } }同时，config.properties放在：
src/main/resources/config.properties✅ 在 IDEA 里运行：一切正常
❌ 打包成 jar 后运行：抛出“找不到 config.properties！”
为什么？
因为IDE 运行时，resources 目录被直接加入 classpath；
而打包后，config.properties 被打进 jar 包内部，必须通过classpath 路径访问。
📌 关键点：
getResourceAsStream("/xxx")中的/表示从classpath 根目录开始查找！
三、图解：Maven 项目打包前后 classpath 的变化
🟢 开发阶段（IDE 运行）：
项目根目录/ ├── src/ │ ├── main/ │ │ ├── java/ → 编译成 .class 放入 target/classes/ │ │ └── resources/ → 复制到 target/classes/ └── target/ └── classes/ ← IDE 的 classpath 指向这里！ ├── com/example/App.class └── config.propertiesJVM 启动时，classpath =target/classes，所以能同时找到类和资源文件。
🔴 打包后（运行 jar）：
my-app.jar ├── META-INF/ │ └── MANIFEST.MF ├── com/ │ └── example/ │ └── App.class └── config.properties ← 注意！它在 jar 根目录！此时，整个 jar 文件就是一个 classpath 单元。App.class要访问config.properties，必须用/config.properties（从根开始）。
如果你写成：
// 错误！没有前导斜杠 App.class.getResourceAsStream("config.properties");JVM 会在com/example/目录下找config.properties，当然找不到！
四、常见 classpath 问题 & 解决方案
| 问题现象 | 原因 | 解决方法 |
|---|---|---|
NoClassDefFoundError | 依赖的 jar 没打进最终包 | 用maven-assembly-plugin或maven-shade-plugin打“fat jar” |
找不到主类 | MANIFEST.MF 没指定 Main-Class | 在 pom.xml 中配置maven-jar-plugin的<mainClass> |
| 资源文件读不到 | 路径写错或未放进 resources | 确保文件在src/main/resources，用/xxx从根路径加载 |
| 第三方库缺失 | 只打包了自己代码，没包含依赖 | 使用 Spring Boot 的spring-boot-maven-plugin（自动打包依赖） |
五、如何打出一个“能跑”的 jar？
方法1：使用 Maven Shade Plugin（推荐给普通 Java 项目）
在pom.xml中添加：
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.5.0</version> <executions> <execution> <phase>package</phase> <goals><goal>shade</goal></goals> <configuration> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.example.App</mainClass> </transformer> </transformers> </configuration> </execution> </executions> </plugin>然后运行：
mvn clean package java -jar target/my-app-1.0.jar # ✅ 能跑！方法2：如果是 Spring Boot 项目
直接用默认插件即可：
./mvnw clean package java -jar target/demo-0.0.1-SNAPSHOT.jar # ✅ 自动包含所有依赖六、调试技巧：如何查看 jar 包里的内容？
# 查看 jar 结构 jar -tf target/my-app.jar # 查看 MANIFEST.MF unzip -p target/my-app.jar META-INF/MANIFEST.MF # 临时解压查看 unzip target/my-app.jar -d temp/如果config.properties不在根目录，说明 Maven 没把它正确打包——检查是否放错了位置！
结语
“IDE 能跑，jar 不能跑”不是玄学，而是classpath 理解不到位的典型表现。
记住三个关键原则：
- 资源文件必须放在
src/main/resources - 用
getResourceAsStream("/文件名")从 classpath 根加载 - 打包时确保依赖和主类配置正确
搞懂 classpath，你就迈出了从“学生代码”到“工程代码”的重要一步！