1. 从一次打包失败说起为什么你需要了解Gradle的Jar生成那天下午项目临近上线我像往常一样在本地执行gradle build准备生成最终的Jar包进行部署。控制台输出一片绿色BUILD SUCCESSFUL 的字样让我安心。然而当我把生成的myapp.jar扔到测试服务器上用java -jar启动时熟悉的启动日志并没有出现取而代之的是一行冰冷的错误信息“没有主清单属性”。我心里“咯噔”一下立刻意识到问题所在这个Jar包虽然包含了所有编译后的.class文件但它是一个普通的、不可执行的库Jar而不是一个可执行的、带有Main-Class清单的应用程序Jar。这个看似简单的错误背后其实是Gradle构建体系中一个非常核心却又容易被新手甚至是有一定经验的开发者混淆的概念生成Jar包的两种不同方式及其适用场景。无论是开发一个微服务后端、一个工具库还是集成第三方SDK理解这两种方式jar任务与bootJar任务的差异是避免部署翻车、构建出符合预期的产物的关键。今天我们就来彻底拆解Gradle中生成Jar的这两种路径让你不仅能打出正确的包更能理解每一步背后的设计逻辑。2. 核心分野普通Jar与可执行Jar的本质区别在深入Gradle的具体任务之前我们必须先厘清一个根本问题Jar包本身就有不同的“使命”。这直接决定了Gradle提供了不同的工具来达成目标。2.1 库Jar作为依赖的“零件”想象一下汽车制造厂。发动机、变速箱、轮胎这些是独立的零部件它们被生产出来是为了组装到整车上。库JarLibrary Jar就扮演着这个“零部件”的角色。它的核心目的是被其他项目引用作为依赖项。一个典型的库Jar比如guava-31.1-jre.jar或fastjson-1.2.83.jar它的内部结构相对纯粹/根目录下是编译好的.class文件按照包路径组织。/META-INF/目录下通常只有一个基础的MANIFEST.MF文件里面可能包含版本、创建工具等信息但最关键的是它没有Main-Class属性。它不包含运行所需的所有依赖。使用者需要在自己的项目中声明对这个Jar的依赖构建工具如Gradle、Maven会负责从仓库下载并组装到类路径中。为什么需要这种Jar为了代码复用和模块化。将通用功能如工具类、网络框架、数据库驱动打包成库Jar可以方便地在多个项目间共享避免重复造轮子。当你开发的是一个供他人调用的SDK、一个工具组件包时你产出的就应该是这种库Jar。2.2 可执行Jar独立运行的“整车”还是用汽车比喻可执行JarExecutable Jar就是一辆已经组装好、加满油、插上钥匙就能开走的整车。它的核心目的是独立运行通常是一个应用程序的入口。一个可执行Jar的典型代表就是Spring Boot应用打出来的包。它的内部结构要复杂得多同样包含应用程序自身的.class文件。关键的/META-INF/MANIFEST.MF文件中必须指定Main-Class属性告诉Java虚拟机从哪个类的main方法启动。为了解决“依赖地狱”它通常会将所有第三方依赖库也打包进来。Spring Boot的bootJar采用了“Fat Jar”或“Uber Jar”的方式即把所有依赖的Jar包解压后重新打包到一个大的Jar文件中。更现代的做法是使用嵌套JarJar in Jar结构在/BOOT-INF/lib/目录下存放所有依赖的完整Jar文件在/BOOT-INF/classes/下存放应用类。为什么需要这种Jar为了部署和分发的简便性。运维人员只需要一个Jar文件配合一个Java运行环境就能在任何地方启动服务无需关心复杂的依赖安装和类路径配置。这对于微服务、命令行工具等场景至关重要。理解了这两种Jar的“人生目标”我们再看Gradle提供的两种生成方式就豁然开朗了。3. 方式一使用标准jar任务生成库Jar这是Gradle Java插件自带的最基础的任务。当你创建一个Java项目并应用了java插件后jar任务就自动可用。3.1 基础用法与产出物分析在你的build.gradle文件中甚至不需要任何额外配置执行gradle jar命令Gradle就会在build/libs/目录下生成一个以项目名命名的Jar文件例如my-project-1.0.0.jar。让我们解压这个Jar看看里面有什么my-project-1.0.0.jar ├── com/ │ └── yourcompany/ │ └── yourproject/ │ ├── Main.class │ └── util/ │ └── Tool.class └── META-INF/ └── MANIFEST.MF查看MANIFEST.MF文件内容通常如下Manifest-Version: 1.0是的它非常简单只包含一个清单版本号没有Main-Class。这就是一个标准的库Jar。如果你尝试用java -jar my-project-1.0.0.jar运行它就会得到文章开头提到的“没有主清单属性”错误。3.2 自定义配置让库Jar更专业虽然基础任务够用但一个成熟的库Jar往往需要更多信息。我们可以通过jar任务配置块来自定义jar { // 1. 自定义Jar包名称和版本 archiveBaseName my-awesome-lib archiveVersion 2.1.0-SNAPSHOT // 也可以更精细地控制archiveFileName ${archiveBaseName.get()}-${archiveVersion.get()}.jar // 2. 排除不需要打包的文件 exclude **/*.properties, **/test/** // 3. 添加自定义清单信息但对于库JarMain-Class通常不在这里加 manifest { attributes( Implementation-Title: project.name, Implementation-Version: project.version, Built-By: System.getProperty(user.name), Built-Date: new Date(), Built-JDK: System.getProperty(java.version) ) // 注意这里没有设置 Main-Class } // 4. 包含源码生成-source.jar时常用但主jar通常不需要 // from sourceSets.main.allSource }配置解析与避坑点archiveBaseName和archiveVersionGradle 7.x之后推荐使用新的APIarchiveBaseName.set(...)但上述写法在大多数情况下兼容。明确设置它们可以避免项目名/版本变更导致产出物名称意外变化。exclude非常重要避免将配置文件、测试代码等无关内容打入生产Jar这可能导致类冲突或信息泄露。使用Ant风格路径匹配如**/*.xml。manifest添加构建信息是良好实践便于追溯。但切记除非你明确在构建一个可执行工具库否则不要在库Jar的manifest里添加Main-Class。这会让使用者困惑且可能引发类加载问题。3.3 实战场景发布到Maven仓库生成库Jar的终极目标往往是发布。结合maven-publish插件你可以轻松将Jar发布到本地、公司私服或Maven Central。plugins { id java id maven-publish } // ... jar 配置同上 ... publishing { publications { mavenJava(MavenPublication) { // 指定我们要发布的组件这里是jar任务产生的组件 from components.java // 自定义POM信息 pom { name 我的超棒库 description 一个解决特定问题的Java库 url http://www.example.com/library licenses { license { name The Apache License, Version 2.0 url http://www.apache.org/licenses/LICENSE-2.0.txt } } developers { developer { id devid name 开发者名字 email emailexample.com } } } } } repositories { // 发布到本地Maven仓库 mavenLocal() // 发布到远程仓库示例 maven { url version.endsWith(SNAPSHOT) ? snapshotsRepoUrl : releasesRepoUrl credentials { username project.findProperty(repoUsername) ?: password project.findProperty(repoPassword) ?: } } } }执行gradle publish或gradle publishToMavenLocal你的库Jar连同POM文件就会被发布出去供其他项目通过implementation com.example:my-awesome-lib:2.1.0-SNAPSHOT引用了。关键经验jar任务生成的产物其“完整性”是相对于编译类路径而言的。它只包含本项目源码编译后的类不包含任何第三方依赖。这是设计使然因为依赖管理应由使用方通过构建工具解决。4. 方式二使用bootJar任务生成可执行JarSpring Boot当你的项目是一个Spring Boot应用时你的目标就是一个可独立运行的、包含所有依赖的Jar包。spring-boot-gradle-plugin插件提供的bootJar任务就是为此而生。4.1bootJar与jar的互斥与共存应用Spring Boot插件后你会立刻发现项目里有了两个任务jar和bootJar。它们是什么关系默认行为Spring Boot插件会禁用标准的jar任务并让bootJar任务成为assemble生命周期任务的依赖。这意味着当你执行gradle build时默认只会生成可执行的bootJar。共存的场景有时你的项目既是可执行应用又想发布一个库Jar比如一个包含可执行示例的SDK。这时你需要重新启用jar任务并区分它们的产出。plugins { id java id org.springframework.boot version 3.2.0 // 这会应用Spring Boot插件 id io.spring.dependency-management version 1.1.4 } // 配置 bootJar bootJar { archiveClassifier boot // 可选为可执行Jar添加分类器如 myapp-1.0.0-boot.jar mainClass com.yourcompany.yourapp.Application // 通常可自动探测但显式指定更安全 } // 重新启用并配置普通的 jar 任务用于生成库Jar jar { archiveClassifier // 主Jar不带分类器 enabled true // 关键重新启用它 }这样配置后执行gradle build会生成两个Jarmyapp-1.0.0.jar库Jar和myapp-1.0.0-boot.jar可执行Jar。archiveClassifier属性帮助区分它们。4.2 深入bootJar内部Fat Jar的构造原理bootJar打出来的包为什么能独立运行我们解压一个典型的Spring Boot 3.x应用Jar看看结构myapp-1.0.0-boot.jar ├── META-INF/ │ └── MANIFEST.MF ├── BOOT-INF/ │ ├── classes/ │ │ └── com/yourcompany/yourapp/... (你的应用类) │ └── lib/ │ ├── spring-boot-3.2.0.jar │ ├── spring-core-6.1.0.jar │ ├── jackson-databind-2.15.0.jar │ └── ... (所有依赖的Jar) ├── org/ │ └── springframework/ │ └── boot/ │ └── loader/ │ ├── JarLauncher.class │ └── ... (Spring Boot的类加载器) └── 其他Spring Boot Loader需要的资源核心机制解读自定义类加载器org.springframework.boot.loader.JarLauncher是真正的入口。MANIFEST.MF中的Main-Class指向它而不是你的Application类。嵌套Jar加载JarLauncher知道如何从/BOOT-INF/lib/加载依赖Jar并从/BOOT-INF/classes/加载应用类。这解决了传统类路径下无法处理Jar中嵌套Jar的问题。依赖隔离你的应用类和所有依赖被清晰地隔离在BOOT-INF目录下与Spring Boot Loader自身的类分开。4.3 高级配置与性能调优bootJar任务提供了丰富的配置选项以适应复杂场景。bootJar { // 1. 包含/排除特定的依赖 requiresUnpack **/some-native-library-*.jar // 解压特定依赖常用于包含本地库的Jar excludes [**/tomcat-embed-*.jar] // 排除特定依赖比如你想使用Jetty而非Tomcat // 2. 分层构建Layer Tools - 提升Docker镜像构建效率 layered { enabled true // 默认分层dependencies, spring-boot-loader, snapshot-dependencies, application // 你可以自定义层规则 includeLayerTools true } // 3. 优化启动时间排除不必要的内容 exclude **/*.vm, **/*.ftl // 排除模板文件运行时可能从外部读取 // 4. 为Jar添加启动脚本生成完全可执行的Jar在Linux/Unix上可直接./app.jar运行 // 注意这需要特定配置且可能受系统安全策略限制 // launchScript { // enabled true // } } // 配合分层构建定义自定义层Gradle 6.0, Spring Boot 2.3 tasks.named(bootJar) { layered { application { intoLayer(static-resources) { include static/**, public/** } intoLayer(config) { include **/*.yml, **/*.properties } intoLayer(application) { include ** } } } }分层构建详解这是Spring Boot 2.3引入的强大特性。它将Jar内容按变更频率分层如依赖、资源、应用代码在制作Docker镜像时可以将稳定的层如依赖缓存起来只重建变更频繁的应用层极大加速镜像构建和推送速度。4.4 常见问题排查与解决即使使用了bootJar打包路上也可能有坑。这里分享几个我踩过的雷问题一bootJar打包失败提示“找不到主类”症状执行gradle bootJar失败错误信息指出无法找到或加载主类。排查检查build.gradle中的mainClass配置是否正确或确认Spring Boot能否自动探测。你的主类必须包含标准的public static void main(String[] args)方法。运行gradle bootRun看应用能否正常启动这能验证主类本身是否正确。检查构建输出目录build/classes/java/main下你的主类.class文件是否存在。可能是编译环节出了问题。解决在bootJar配置中显式指定主类mainClass 全限定类名。问题二生成的Jar包运行时报告ClassNotFoundException或NoSuchMethodError症状Jar包能启动但在调用某个特定类或方法时崩溃。排查依赖冲突这是最常见原因。使用gradle dependencies或gradle dependencyInsight --dependency some-library命令分析依赖树查看是否有同一个库的多个版本。Spring Boot的dependencyManagement通常能管理好版本但引入第三方库时可能破坏平衡。打包遗漏检查BOOT-INF/lib目录下是否缺失了某个关键的依赖Jar。可能是该依赖被标记为runtimeOnly或compileOnly而bootJar默认只打包runtimeClasspath上的依赖。对于需要打包的compileOnly依赖如Lombok的代理虽然它本身不需要需要特殊处理。本地Jar未打包如果你通过flatDir引入了本地Jar文件确保它们被正确添加到runtimeClasspath。解决对于依赖冲突使用exclude规则排除冲突的传递性依赖。implementation(org.third:some-library) { exclude group: org.conflict, module: unwanted-module }对于必须打包的compileOnly依赖可以将其添加到bootJar的类路径中谨慎使用bootJar { classpath configurations.compileClasspath }问题三Jar包体积过大症状一个简单的Web应用Jar包达到80MB以上。排查使用gradle dependencies查看是否引入了不必要的庞大依赖如旧版本的数据库驱动、未使用的工具包。解压Jar包查看BOOT-INF/lib中哪些Jar文件体积最大。检查是否将前端静态资源如node_modules错误地打包进了Jar。解决使用implementation而非过时的compile避免传递不需要的依赖。排除特定依赖见上文excludes配置。对于前端资源考虑使用CDN或单独部署而非打包进Jar。使用ProGuard或Spring Boot提供的spring-boot-thin-launcher创建瘦身Jar仅包含运行时动态下载依赖的元数据但这会引入额外的复杂度。5. 进阶自定义打包与多模块项目中的Jar生成在真实的、复杂的项目中打包需求往往超出上述两种标准模式。5.1 创建自定义的“Fat Jar”非Spring Boot项目如果你的项目不是Spring Boot应用但也需要生成一个可执行的、包含所有依赖的Fat Jar你可以自定义jar任务来实现。plugins { id java } // 创建一个名为 fatJar 的自定义任务 tasks.register(fatJar, Jar) { archiveClassifier all // 产出物为 myapp-1.0.0-all.jar duplicatesStrategy DuplicatesStrategy.EXCLUDE // 处理重复文件的策略 manifest { attributes Main-Class: com.yourcompany.yourapp.Main // 必须指定主类 } // 关键步骤将项目编译输出和所有运行时依赖打包到一起 from sourceSets.main.output dependsOn configurations.runtimeClasspath from { configurations.runtimeClasspath.findAll { it.name.endsWith(jar) }.collect { zipTree(it) } } }原理解析from sourceSets.main.output包含你自己编译的类文件。from { configurations.runtimeClasspath... }这是一个Groovy闭包它收集所有runtimeClasspath配置下的Jar文件即所有运行时依赖并对每个Jar执行zipTree相当于将其解压后的内容合并到最终的Fat Jar中。duplicatesStrategy当多个依赖Jar中存在相同路径的文件如META-INF/LICENSE.txt时指定处理策略。EXCLUDE表示排除重复使用第一个遇到的。警告这种简单的合并方式有局限性。如果不同依赖Jar中有同名的类或资源文件可能会被覆盖导致难以预料的行为。对于复杂项目建议使用专业的阴影插件Shadow Plugin。5.2 使用Shadow插件推荐Gradle Shadow插件是创建Fat Jar的工业标准它提供了更强大、更安全的依赖合并和重定位功能。plugins { id java id com.github.johnrengelman.shadow version 8.1.1 // 使用最新版本 } // 应用插件后会新增 shadowJar 任务替代 jar 任务作为默认打包任务 shadowJar { archiveClassifier // 产出物替换主Jar manifest { attributes Main-Class: com.yourcompany.yourapp.Main } // 重定位易冲突的包名 relocate com.google.common, shadowed.com.google.common minimize() // 尝试移除未使用的类减小体积需谨慎测试 } // 如果你还需要普通的库Jar可以单独配置 jar 任务 jar { archiveClassifier original enabled true }执行gradle shadowJar即可生成优化后的Fat Jar。Shadow插件会智能地合并资源、处理清单文件并通过relocate解决常见的依赖冲突比如Guava。5.3 多模块项目中的打包策略在一个包含多个子模块的Gradle项目中打包策略需要仔细规划。场景一个父项目parent包含两个子模块core核心库和app可执行应用。app依赖core。core/build.gradle它应该生成一个库Jar供app和其他模块使用。// core模块只生成普通jar plugins { id java-library } // 使用java-library插件提供更清晰的API/实现分离 // jar任务配置如前所述用于发布app/build.gradle它需要生成一个可执行Fat Jar并且必须包含core模块的代码。plugins { id java id org.springframework.boot // 假设是Spring Boot应用 } dependencies { implementation project(:core) // 依赖core模块 // ... 其他依赖 } bootJar { // Spring Boot的bootJar会自动处理对子模块的依赖将其编译后的类打包进来。 // 无需特殊配置。 } // 如果需要也可以禁用app模块自身的普通jar任务因为主要产物是bootJar jar { enabled false }关键点在多模块项目中子模块间的依赖通过project(:module-name)声明。Gradle会确保依赖模块先被编译。对于bootJar或shadowJar它们会递归地将这些项目依赖的类文件打包进最终的Fat Jar中而不是打包子模块的Jar文件。这确保了代码是最新的且没有冗余的Jar嵌套。6. 构建优化与持续集成中的打包实践在团队开发和CI/CD流水线中打包环节的稳定性和效率至关重要。6.1 加速构建缓存与并行化Gradle构建缓慢是常见痛点尤其是在生成Fat Jar时。启用构建缓存在gradle.properties或命令行中设置org.gradle.cachingtrue。Gradle会缓存任务输出如编译结果下次构建时直接复用极大加速增量构建。启用并行执行在gradle.properties中设置org.gradle.paralleltrue。对于多模块项目Gradle会尝试并行构建独立的模块。优化依赖解析使用国内镜像源如阿里云Maven仓库加速依赖下载。在项目根目录的build.gradle或settings.gradle中配置repositories { maven { url https://maven.aliyun.com/repository/public/ } mavenCentral() }对于CI环境可以考虑启用依赖缓存或使用离线模式--offline但需确保本地缓存已预先填充。6.2 在CI/CD中可靠地打包在Jenkins、GitLab CI、GitHub Actions等环境中你需要确保打包环境的一致性和可重复性。指定Gradle版本使用Gradle Wrappergradlew。将gradle/wrapper/gradle-wrapper.properties文件提交到版本库确保所有开发者和CI服务器使用完全相同的Gradle版本。清理构建环境CI任务开始时执行./gradlew clean清理之前的构建产物避免残留文件干扰。分离构建阶段# 示例GitHub Actions workflow jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Set up JDK uses: actions/setup-javav4 with: { java-version: 17, distribution: temurin } - name: Grant execute permission for gradlew run: chmod x gradlew - name: Build with Gradle run: ./gradlew assemble # 或 bootJar 但不运行测试 - name: Run Tests run: ./gradlew test - name: Upload Artifact uses: actions/upload-artifactv4 with: { name: application, path: app/build/libs/*.jar } # 上传产出的Jar包构建参数化通过-P传递构建参数实现环境差异化打包。例如为不同环境dev/staging/prod打包不同的配置文件。// build.gradle def env project.hasProperty(buildEnv) ? project.buildEnv : dev processResources { // 处理资源文件如application.yml filesMatching(application*.yml) { expand(project.properties) // 将Gradle属性替换到配置文件中 filter(ReplaceTokens, tokens: [env: env]) // 或用Token替换 } }命令行执行./gradlew bootJar -PbuildEnvprod。6.3 版本管理与产出物命名清晰的版本和产出物命名是运维和追溯的基础。使用gradle.properties管理版本# gradle.properties version2.5.0在build.gradle中直接引用project.version。动态版本号在CI中可以使用Git commit hash或构建号作为版本的一部分。def gitHash git rev-parse --short HEAD.execute().text.trim() def buildNumber System.getenv(BUILD_NUMBER) ?: SNAPSHOT version ${project.version}-${buildNumber}-${gitHash}标准化产出物名称在jar或bootJar任务中统一配置。bootJar { archiveFileName ${project.name}-${project.version}-${new Date().format(yyyyMMddHHmm)}.jar }从一次简单的gradle build到为生产环境打造稳定、高效、可追溯的构建流水线理解并掌握Gradle生成Jar的两种方式及其变体是每一位Java开发者进阶之路上的必修课。它不仅仅是打出一个包更是对项目结构、依赖管理、交付流程的深刻理解。下次当你执行打包命令时希望你能清晰地知道正在生成的是哪一个“角色”的Jar以及它将去往何方。