使用Gradle Shadow插件构建包含所有依赖的可执行JAR包-java教程-PHP中文网

使用Gradle Shadow插件构建包含所有依赖的可执行JAR包

心靈之曲

发布： 2025-10-31 15:41:18

原创

518人浏览过

使用gradle shadow插件构建包含所有依赖的可执行jar包

本教程详细介绍了如何利用Gradle的Shadow插件，将Java项目及其所有依赖项打包成一个独立的、可执行的“胖JAR”（或称“Uber JAR”）。通过在主模块的`build.gradle`中配置插件并指定主类，开发者可以轻松生成一个包含所有运行时依赖的JAR文件，从而简化应用的部署和执行过程，实现`java -jar`命令的直接运行。

使用Gradle Shadow插件构建包含依赖的可执行JAR包

在Java项目开发中，将应用程序及其所有运行时依赖项打包成一个单一的可执行JAR文件（通常称为“胖JAR”或“Uber JAR”）是一种常见需求。这极大地简化了应用程序的分发和部署，用户只需一个命令即可运行。标准的Gradle jar任务通常只包含项目自身的编译输出，而不包括其依赖库。为了解决这个问题，我们可以利用Gradle的com.github.johnrengelman.shadow插件，即Shadow插件。

本教程将指导您如何在Gradle项目中，特别是多项目结构下，正确配置并使用Shadow插件来生成一个包含所有依赖的可执行JAR包。

1. 理解settings.gradle与build.gradle的区别

在开始之前，需要明确settings.gradle和build.gradle的角色。

立即进入“豆包AI人工智官网入口”；

立即学习“豆包AI人工智能在线问答入口”；

settings.gradle: 这个文件定义了Gradle项目的结构，主要用于声明包含哪些子项目（include 'subproject-name'）。它不用于定义单个项目的构建逻辑或插件。
build.gradle: 每个项目（包括根项目和所有子项目）都有一个build.gradle文件，用于定义该项目的具体构建逻辑，如依赖管理、任务定义和插件应用。

因此，Shadow插件需要应用于您希望打包成可执行JAR的具体模块（子项目）的build.gradle文件中。

2. 在主模块中应用Shadow插件

假设您的主应用程序逻辑位于一个名为app的子项目中。您需要在app/build.gradle文件中应用Shadow插件。

首先，在您的项目根目录下的build.gradle文件中（或者在app/build.gradle的plugins块中），添加Shadow插件的声明：

// build.gradle (root project) 或 app/build.gradle
plugins {
    id 'java' // 确保您的项目是Java项目
    id 'application' // 推荐使用application插件来管理主类
    id 'com.github.johnrengelman.shadow' version '7.1.2' // 应用Shadow插件
}

登录后复制

请确保com.github.johnrengelman.shadow的版本号是最新的稳定版本。您可以在Shadow插件的GitHub仓库找到最新版本信息。

3. 配置应用程序主类

为了使生成的JAR文件可执行，您需要明确指定应用程序的入口点，即主类。这可以通过两种方式实现，建议同时配置以确保兼容性和清晰性：

a. 使用application插件配置主类

如果您已经应用了application插件，可以在其配置块中指定mainClass：

// app/build.gradle
application {
    // 定义应用程序的主类
    mainClass = 'com.example.app.Main' // 替换为您的实际主类路径
}

登录后复制

b. 在jar任务的manifest中设置Main-Class属性

豆包爱学

豆包旗下AI学习应用

674

查看详情

这是标准的Java JAR规范，指定了JAR文件启动时应执行的类。Shadow插件会继承这个配置。

// app/build.gradle
jar {
    manifest {
        attributes "Main-Class": "com.example.app.Main" // 替换为您的实际主类路径
    }
}

登录后复制

示例代码片段（app/build.gradle）:

plugins {
    id 'java'
    id 'application'
    id 'com.github.johnrengelman.shadow' version '7.1.2' // 使用您选择的版本
}

repositories {
    mavenCentral() // 或其他您的依赖仓库
}

dependencies {
    // 您的项目依赖
    implementation 'org.slf4j:slf4j-api:1.7.30'
    // ... 其他依赖
}

application {
    mainClass = 'com.example.app.Main' // 您的主类
}

jar {
    manifest {
        attributes "Main-Class": "com.example.app.Main" // 确保和application.mainClass一致
    }
}

// 可选：配置shadowJar任务的输出名称等
shadowJar {
    archiveBaseName.set('TrendAnalyzer') // 设置生成的JAR文件基础名称
    archiveClassifier.set('all') // 设置分类器，最终文件名为 TrendAnalyzer-all.jar
    // 更多配置，如排除某些文件，依赖重定位等
}

登录后复制

4. 构建Shadow JAR

完成上述配置后，您可以通过运行Gradle任务来生成包含所有依赖的可执行JAR文件。在项目根目录下（settings.gradle所在目录），执行以下命令：

./gradlew shadowJar

登录后复制

如果您在Windows环境下，可以使用gradlew.bat shadowJar。

Gradle将执行shadowJar任务，编译您的代码，并将其所有运行时依赖项（包括传递性依赖）合并到一个JAR文件中。

5. 查找并运行生成的JAR文件

构建成功后，生成的JAR文件通常位于您配置Shadow插件的模块的build/libs目录下。例如，如果是在app模块中配置的，那么文件路径将是app/build/libs/。

默认情况下，Shadow插件会生成一个名为[项目名称]-[版本]-all.jar的文件（例如，app-1.0-SNAPSHOT-all.jar）。如果您在shadowJar配置块中自定义了archiveBaseName和archiveClassifier，文件名将相应改变（例如，TrendAnalyzer-all.jar）。

要运行这个JAR文件，您只需使用标准的Java命令：

java -jar app/build/libs/TrendAnalyzer-all.jar

登录后复制

请将app/build/libs/TrendAnalyzer-all.jar替换为您的实际JAR文件路径和名称。

注意事项与总结

java -cp vs java -jar: 当您使用Shadow插件创建了包含所有依赖的“胖JAR”后，推荐使用java -jar命令来运行。java -jar会读取JAR文件中的META-INF/MANIFEST.MF文件，并根据Main-Class属性启动应用程序。而java -cp（或java -classpath）通常用于指定类路径，它需要您手动列出所有依赖的JAR文件，这对于“胖JAR”来说是不必要的。
依赖冲突处理: Shadow插件在合并依赖时，能够处理不同库中可能存在的类冲突（例如，不同版本库中包含同名类）。它通过“依赖重定位”（relocation）机制，将冲突的类移动到不同的包下，从而避免运行时错误。
文件大小: 生成的“胖JAR”文件会包含所有依赖，因此其大小会比普通JAR文件大很多。这是预期的行为。
多项目结构: 在多项目结构中，确保将Shadow插件应用到包含您主应用程序入口点的那个子项目（模块）的build.gradle文件中。

通过遵循本教程的步骤，您可以轻松地为您的Gradle Java项目创建可独立运行的、包含所有依赖的JAR包，从而极大地简化应用程序的部署和分发。

以上就是使用Gradle Shadow插件构建包含所有依赖的可执行JAR包的详细内容，更多请关注php中文网其它相关文章！