IntelliJ IDEA打包时依赖缺失如何解决？

Question

在使用 IntelliJ IDEA 进行项目打包（如生成 JAR 文件）时，常遇到第三方依赖未被打包进去的问题，导致运行时抛出 `ClassNotFoundException` 或 `NoClassDefFoundError`。该问题通常出现在使用默认的 "Extracted to the target JAR" 选项之外的打包方式，或未正确配置 Maven/Gradle 构建插件。尤其在手动通过 Artifacts 配置打包时，若未勾选“Copy to output directory and link to manifest”或遗漏依赖库路径，便会引发依赖缺失。如何确保所有运行时依赖被正确包含，是开发者高频面临的挑战。

Answer 1

1. 问题背景与常见表现

在使用 IntelliJ IDEA 进行 Java 项目打包时，开发者常通过 Build → Build Artifacts 或结合 Maven/Gradle 构建工具生成可执行 JAR 文件。然而，在运行生成的 JAR 时，频繁出现 ClassNotFoundException 或 NoClassDefFoundError 异常，根本原因通常是：第三方依赖未被正确包含进最终的 JAR 包中。

该问题多发于以下场景：

• 手动配置 Artifacts 打包时，未将依赖库复制到输出目录；
• Maven 使用默认 maven-jar-plugin 而未配置 maven-assembly-plugin 或 maven-shade-plugin；
• Gradle 中未使用 shadowJar 插件或未正确声明任务；
• Manifest 文件未设置正确的 Class-Path 或主类入口。

2. 深度剖析：IDEA Artifacts 配置机制

IntelliJ IDEA 的 Artifact 是一种打包定义，用于指定哪些内容应被打包进 JAR/WAR 等归档文件。其核心配置位于：
File → Project Structure → Artifacts。

常见的 Artifact 输出类型包括：

类型	说明	是否包含依赖
JAR from modules with dependencies	可选择打包方式（解压、引用、独立）	取决于选项
Exploded	未压缩的目录结构，便于调试	否
Empty	需手动添加内容	否

若选择“JAR from modules with dependencies”，关键在于“Library files”处理方式：

1. Extracted to the target JAR：将所有依赖类文件解压并合并至输出 JAR，形成“fat JAR”；
2. Copy to output directory and link via Manifest：依赖以独立 JAR 存放于 lib 目录，并在 MANIFEST.MF 中添加 Class-Path；
3. Link library only：仅记录路径，不复制，极易导致运行时缺失。

3. 常见错误配置示例

以下为典型的错误 Artifact 设置导致依赖丢失：

// 错误案例：未勾选依赖复制
Output Layout:
├── module-classes/
└── (无 lib 文件夹)
Manifest: Main-Class: com.example.Main
         Class-Path: （空）

此时运行命令：

java -jar myapp.jar

将直接抛出：

Exception in thread "main" java.lang.NoClassDefFoundError: org/springframework/context/ApplicationContext

4. 解决方案一：正确配置 IDEA Artifacts

确保依赖被包含，应按如下步骤操作：

1. 进入 Project Structure → Artifacts；
2. 选择或新建 JAR → From modules with dependencies；
3. 在弹出窗口中，选择 "Copy to output directory and link to manifest"；
4. 确认输出路径为 lib/，并保留默认的相对路径引用；
5. 检查生成的 MANIFEST.MF 是否包含类似内容：

Manifest-Version: 1.0
Main-Class: com.example.Main
Class-Path: lib/spring-context-5.3.21.jar lib/commons-lang3-3.12.0.jar

同时，构建后目录结构应为：

myapp.jar
└── lib/
    ├── spring-core-*.jar
    └── commons-collections4-*.jar

5. 解决方案二：使用 Maven 构建 Fat JAR

推荐使用 maven-shade-plugin 将所有依赖打包进单一 JAR：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.1</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.Main</mainClass>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

执行 mvn clean package 后，生成的 original- 和 -shaded.jar 中后者即为可独立运行的 fat jar。

6. 解决方案三：Gradle 中使用 Shadow Plugin

在 Gradle 项目中引入 com.github.johnrengelman.shadow 插件：

plugins {
    id 'com.github.johnrengelman.shadow' version '7.1.2'
    id 'java'
}

shadowJar {
    manifest {
        attributes['Main-Class'] = 'com.example.Main'
    }
}

构建命令：

./gradlew shadowJar

输出 app-all.jar 即包含全部依赖。

7. 自动化验证流程图

graph TD A[开始打包] --> B{使用Maven/Gradle?} B -- 是 --> C[配置shade/shadow插件] B -- 否 --> D[配置Artifacts] D --> E[选择Extracted或Copy to output] C --> F[执行mvn/gradle build] E --> F F --> G[检查输出JAR内容] G --> H[运行 java -jar test.jar] H --> I{异常抛出?} I -- 是 --> J[回溯依赖缺失类] I -- 否 --> K[打包成功] J --> L[检查MANIFEST或插件配置] L --> C

8. 最佳实践建议

• 优先使用构建工具（Maven/Gradle）而非纯 IDEA 打包，提升可重复性；
• 生产环境推荐生成 fat jar，避免部署时依赖缺失；
• 若需模块化部署，采用 “lib + Class-Path” 方式，但需确保目录结构一致；
• 定期审查 target/lib 或 build/libs 输出内容，可用 jar -tf xxx.jar 查看内部结构；
• 启用 CI/CD 流水线自动执行打包并验证运行可行性；
• 对 Spring Boot 项目，默认使用 spring-boot-maven-plugin，无需额外配置；
• 注意排除不必要的传递依赖，防止 JAR 过大；
• 使用 jdeps 工具分析运行时依赖边界；
• 在多模块项目中，确保父 POM 正确聚合子模块依赖；
• 调试时可通过 -verbose:class 参数观察类加载过程。