Gradle教程：使用Shadow Jar插件创建带依赖的可执行JAR文件-java教程-PHP中文网

Gradle教程：使用Shadow Jar插件创建带依赖的可执行JAR文件

碧海醫心

发布： 2025-10-31 12:34:19

原创

780人浏览过

Gradle教程：使用Shadow Jar插件创建带依赖的可执行JAR文件

本教程详细介绍如何使用gradle的shadow jar插件，将应用程序及其所有依赖项打包成一个独立的、可执行的jar文件。通过配置主模块的build.gradle文件，并运行特定的gradle任务，您可以轻松生成一个“胖jar”，实现便捷的部署和通过`java -jar`命令直接运行。

1. 理解可执行JAR与依赖管理

在Java开发中，将应用程序及其所有外部库（依赖项）打包成一个独立的、可执行的JAR文件是常见的部署需求。传统的java -cp命令需要手动指定所有依赖的路径，这在依赖众多时变得非常繁琐。为了简化部署和运行，我们通常会寻求一种方式来生成一个“胖JAR”（Fat Jar），即一个包含所有应用程序代码和其依赖的单一JAR文件，可以直接通过java -jar命令运行。

对于Gradle项目，尤其是多模块项目，虽然settings.gradle文件定义了项目的整体结构和模块包含关系，但具体的打包配置通常在每个模块的build.gradle文件中进行。本教程将重点介绍如何利用com.github.johnrengelman.shadow插件（通常称为Shadow Jar插件）来实现这一目标。

2. Shadow Jar插件简介

Shadow Jar插件是一个强大的Gradle插件，它能够将项目及其所有运行时依赖项合并到一个单独的JAR文件中。它的核心功能包括：

依赖合并（Shading）: 将所有依赖的类文件提取并重新打包到主JAR中。
类重定位（Relocation）: 允许重命名依赖包中的类，以避免在运行时与其他应用程序或库发生类路径冲突。
资源合并: 合并来自不同JAR的资源文件，如META-INF/services。
清单文件（Manifest）配置: 自动配置JAR的META-INF/MANIFEST.MF文件，特别是Main-Class属性，使其成为可执行JAR。

通过使用Shadow Jar插件，您可以轻松创建出可以直接运行的“胖JAR”，大大简化了应用程序的发布和部署流程。

3. 配置Shadow Jar插件

要使用Shadow Jar插件，您需要在希望生成可执行JAR的主模块的build.gradle文件中进行配置。

3.1 应用插件

首先，在主模块的build.gradle文件的plugins块中添加Shadow Jar插件。建议同时应用application插件，它能更好地辅助管理应用程序的主类。

plugins {
    id 'java' // 如果是Java项目，通常会包含此插件
    id 'application' // 用于定义应用程序的主类
    id 'com.github.johnrengelman.shadow' version '7.1.2' // Shadow Jar插件
}

登录后复制

请注意，version '7.1.2'应替换为当前或您项目兼容的最新版本。您可以在Shadow Jar插件的GitHub页面找到最新版本信息。

3.2 定义应用程序主类

为了使JAR文件可执行，您需要明确指定应用程序的入口点，即包含public static void main(String[] args)方法的类。这可以通过两种方式实现：

使用application插件配置: 这是推荐的方式，它使得主类定义更加清晰。

application {
    // 定义应用程序的主类，例如 'com.example.app.MainClass'
    mainClass = 'jaso92559.app.App'
}

登录后复制

直接在jar任务的manifest中配置: 这种方式也有效，但通常与application插件结合使用更佳。Shadow Jar插件在生成shadowJar时会尊重这些配置。
```
jar {
    manifest {
        attributes "Main-Class": "jaso92559.app.App"
    }
}
```
登录后复制
当同时使用application插件和jar任务的manifest配置时，application插件的mainClass通常会被Shadow Jar插件优先考虑并写入最终的shadowJar的MANIFEST.MF中。为了避免潜在的混淆，建议主要通过application块来定义主类。

行者AI
行者AI绘图创作，唤醒新的灵感，创造更多可能

100

查看详情

完整的配置示例可能如下所示：

// build.gradle (主模块)

plugins {
    id 'java'
    id 'application'
    id 'com.github.johnrengelman.shadow' version '7.1.2' // 请替换为最新版本
}

// 定义应用程序的主类
application {
    mainClass = 'jaso92559.app.App' // 替换为您的应用程序主类
}

// 示例：如果需要对普通jar任务进行额外配置，但通常shadowJar会处理大部分
jar {
    manifest {
        attributes "Main-Class": "jaso92559.app.App" // 确保Main-Class属性被设置
    }
}

// 其他项目配置，如依赖项等
repositories {
    mavenCentral()
}

dependencies {
    // 您的项目依赖
    implementation 'com.google.guava:guava:31.1-jre'
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
}

tasks.named('test') {
    useJUnitPlatform()
}

登录后复制

4. 生成可执行JAR文件

配置完成后，您可以通过运行Gradle的shadowJar任务来生成包含所有依赖的可执行JAR文件。

在项目根目录（settings.gradle文件所在的目录）下，打开命令行或终端，执行以下命令：

./gradlew shadowJar

登录后复制

或者在Windows系统上：

gradlew shadowJar

登录后复制

Gradle将会编译您的项目，并使用Shadow Jar插件将所有依赖项打包到最终的JAR文件中。

5. 运行生成的JAR文件

任务成功执行后，生成的JAR文件通常位于主模块的build/libs/目录下。文件的命名约定通常是[module-name]-all.jar或[module-name]-[version]-all.jar。例如，如果您的模块名为app，则可能生成app-all.jar。

您可以通过以下命令直接运行这个“胖JAR”：

java -jar app-all.jar

登录后复制

替换app-all.jar为实际生成的文件名。如果一切配置正确，您的应用程序将会启动。

6. 总结与注意事项

插件位置: Shadow Jar插件应应用于需要打包成可执行JAR的具体模块的build.gradle文件，而不是根build.gradle或settings.gradle。
主类定义: 确保application.mainClass或jar.manifest.attributes["Main-Class"]正确指向您的应用程序入口类。
版本管理: 定期检查并更新Shadow Jar插件到最新版本，以获取性能改进和新功能。
冲突解决: 在极少数情况下，如果依赖中存在类名冲突或资源冲突，Shadow Jar插件提供了relocate和mergeServiceFiles等高级配置选项来解决这些问题。
文件大小: 生成的“胖JAR”会包含所有依赖，因此文件大小会比普通JAR大很多，这是正常的。