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

Gradle项目构建：使用Shadow插件创建包含所有依赖的独立可执行JAR包

霞舞

发布： 2025-10-31 14:16:23

原创

899人浏览过

Gradle项目构建：使用Shadow插件创建包含所有依赖的独立可执行JAR包

本文详细介绍了如何在gradle项目中，特别是多模块场景下，利用`com.github.johnrengelman.shadow`插件构建一个包含所有运行时依赖的独立可执行jar包。通过配置主模块的`build.gradle`文件并执行`shadowjar`任务，开发者可以轻松生成一个可直接运行的应用程序jar文件，简化部署和分发过程。

引言：为何需要独立可执行JAR包？

在Java应用程序开发中，我们常常需要将应用程序及其所有依赖打包成一个单一的、可直接运行的JAR文件，以便于部署和分发。标准的Gradle jar任务通常只打包项目自身的类文件，而不包含其运行时依赖。这意味着，如果尝试使用 java -cp your-app.jar your.MainClass 命令运行，但没有将所有依赖项正确添加到classpath中，程序将无法启动并报错。

com.github.johnrengelman.shadow插件正是为了解决这一痛点而生。它允许我们将项目的所有直接和间接依赖项合并到一个“胖JAR”（Fat JAR）中，使其成为一个完全独立的应用程序包，无需外部依赖即可运行。

Shadow插件核心功能解析

Shadow插件的核心功能在于其能够递归地查找项目的所有运行时依赖，并将它们解压、重定位（如果需要，以避免不同库之间潜在的类名冲突），然后重新打包到主JAR文件中。最终生成一个包含所有必需代码的单一JAR文件，可以直接通过 java -jar 命令运行，极大地简化了应用程序的部署和分发过程。

配置与构建独立可执行JAR包

要使用Shadow插件创建包含所有依赖的独立可执行JAR包，请遵循以下步骤：

1. 引入Shadow插件

在你的主应用程序模块（通常是包含 main 方法的模块）的 build.gradle 文件中，添加Shadow插件的声明。需要注意的是，尽管 settings.gradle 文件用于定义多模块项目的结构，但插件的实际应用和配置是在具体的模块 build.gradle 文件中进行的。

plugins {
    id 'java' // 如果是Java项目，确保引入java插件
    id 'application' // 可选，但推荐用于定义主类和生成启动脚本
    id 'com.github.johnrengelman.shadow' version '7.1.2' // 请根据需要选择最新版本
}

登录后复制

id 'java' 插件是Java项目的基础。
id 'application' 插件是可选的，但它提供了一些便利，例如 run 任务和生成平台相关的启动脚本。
id 'com.github.johnrengelman.shadow' 引入了Shadow插件本身。请务必使用最新的稳定版本。

2. 配置主类

为了让Gradle知道哪个类是应用程序的入口点，以及在生成JAR文件时在 MANIFEST.MF 中正确设置 Main-Class 属性，我们需要进行如下配置。

application {
    // 定义应用程序的主类，供'application'插件使用，例如'run'任务
    mainClass = 'jaso92559.app.App' // 替换为你的实际主类路径
}

jar {
    manifest {
        // 在JAR的MANIFEST.MF文件中定义主类，供'java -jar'命令使用
        attributes "Main-Class": "jaso92559.app.App" // 替换为你的实际主类路径
    }
}

登录后复制

application.mainClass: 这个配置主要用于 application 插件提供的 run 任务和生成启动脚本时。
jar.manifest.attributes "Main-Class": 这是 java -jar 命令执行JAR文件时所必需的。Shadow插件在构建 shadowJar 时会继承这些配置，确保生成的独立JAR文件能够正确启动。

3. 执行构建任务

在项目的根目录下（即 settings.gradle 所在的目录），打开终端并执行Shadow插件提供的构建任务：

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

查看详情

./gradlew shadowJar

登录后复制

Gradle将开始构建过程，编译代码，并将所有依赖项解压并重新打包到最终的JAR文件中。

构建成功后，你将在主模块的 build/libs 目录下找到生成的独立可执行JAR文件。其命名通常为 [moduleName]-all.jar 或 [moduleName]-[version]-all.jar。例如，如果你的主模块名为 app，则可能生成 app-all.jar。

4. 运行应用程序

生成的JAR文件可以直接通过 java -jar 命令运行：

java -jar app-all.jar

登录后复制

此时，应用程序将启动，无需手动指定任何依赖项的classpath，因为它已经包含了所有必需的库。

注意事项与最佳实践

多模块项目中的应用： 如果你的项目是多模块结构，settings.gradle 文件用于定义这些模块（例如 include 'app'）。但Shadow插件的配置和应用应在 包含 main 方法的那个具体模块 的 build.gradle 文件中进行。例如，如果 app 模块是你的主应用模块，则插件配置应位于 app/build.gradle。
版本管理： 始终关注Shadow插件的最新版本，以获取最新的功能、性能优化和bug修复。
依赖冲突： Shadow插件提供了依赖重定位（Relocation）功能，可以在不同依赖库使用相同包名但不同版本时避免冲突。对于复杂的冲突场景，可能需要手动配置重定位规则。
JAR文件大小： 由于包含了所有依赖，生成的JAR文件会相对较大。这是独立可执行的必然代价，也是其便捷性的体现。
Main-Class 配置： 确保 application.mainClass 和 jar.manifest.attributes "Main-Class" 中的类路径与你的实际主类完全一致，否则JAR文件可能无法正确启动。

总结

通过引入 com.github.johnrengelman.shadow 插件并进行简单的配置，Gradle开发者可以轻松地将复杂的Java应用程序及其所有依赖项打包成一个单一的、可独立运行的JAR文件。这大大简化了应用程序的部署和分发流程，提升了开发效率和用户体验，使得应用程序的交付变得更加高效和可靠。

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