Gradlew Jar输出路径解析与Java CLI应用打包指南

本文旨在解决gradlew jar命令未按预期生成jar包的问题，特别是针对输出路径的常见误解。我们将深入探讨gradle构建系统如何处理jar包生成，分析多项目结构对输出路径的影响，并提供java命令行接口（cli）应用程序的最佳分发策略，包括使用gradle的`application`插件、自包含可执行文件以及其他高级打包方式。

1. 理解gradlew jar命令与JAR包输出

在使用Gradle构建Java项目时，gradlew jar命令负责编译源代码并将其打包成一个可执行的JAR文件。然而，有时开发者会发现执行该命令后，在预期的build/libs目录下找不到生成的JAR包，这通常是由于对项目结构和Gradle默认行为的误解造成的。

1.1 默认JAR包输出路径

对于大多数标准的单模块Gradle项目，当应用了java或application插件时，jar任务生成的JAR包默认会存放在项目的根目录下的build/libs目录中。例如，如果你的项目根目录是my-app/，那么JAR包的路径通常是my-app/build/libs/my-app.jar。

1.2 多项目结构下的输出路径

在多项目（multi-project）Gradle构建中，情况会变得有所不同。如果你的应用程序是一个子项目（例如，名为app的子项目），并且该子项目应用了application插件，那么其生成的JAR包将位于该子项目的build/libs目录中。从项目根目录来看，路径会是root-project/app/build/libs/app.jar。

这正是许多开发者容易混淆的地方。当从根项目运行gradlew jar时，Gradle会为所有适用子项目执行jar任务，但每个子项目的输出都会在其自身的build/libs目录下。

立即学习“Java免费学习笔记（深入）”；

2. 分析build.gradle.kts配置与输出路径

让我们以上述问题中提供的build.gradle.kts文件为例进行分析：

plugins {
    application
    id("com.diffplug.spotless") version "6.12.0"
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("junit:junit:4.13.2")
    implementation("com.google.guava:guava:30.1-jre")
    implementation("info.picocli:picocli:4.7.0")
    annotationProcessor("info.picocli:picocli-codegen:4.7.0")
    implementation("io.vavr:vavr:0.10.4")
}

application {
    mainClass.set("testlauncher.command.Runner")
}

subprojects {
    apply {
        plugin("com.diffplug.spotless")
    }
}

spotless {
    java {
        importOrder()
        removeUnusedImports()
        googleJavaFormat()
    }
}

project.tasks.findByName("build")?.dependsOn(project.tasks.findByName("spotlessApply"))

该配置文件展示了一个典型的Java应用程序构建脚本，使用了application插件来支持CLI应用。

• application插件: 这个插件不仅提供了run任务来运行应用程序，还会自动配置jar任务来生成包含所有应用程序类和资源的JAR包，以及distZip/distTar任务来创建包含所有依赖项和启动脚本的发布包。
• mainClass.set(...): 指定了应用程序的入口点，这是生成可执行JAR包和发布包的关键。

根据此配置：

• 如果是单项目构建（即build.gradle.kts位于项目根目录），那么执行gradlew jar后，JAR包通常会生成在./build/libs/目录下。
• 如果是多项目构建，且此build.gradle.kts位于一个名为app的子项目目录下（例如，root-project/app/build.gradle.kts），那么JAR包将生成在./app/build/libs/目录下。这正是原问题中开发者最终找到JAR包的实际位置。

如何确认JAR包的实际路径？

你可以通过查看Gradle的构建日志来确认jar任务的输出路径。在执行gradlew jar后，通常会有类似以下行的输出：

豆包爱学

豆包旗下AI学习应用

674

查看详情

> Task :jar
...
BUILD SUCCESSFUL in Xs
2 actionable tasks: 2 executed

虽然直接的输出路径不总是显式列出，但你可以通过Gradle的API来查询：

gradlew -q printJarPath

在你的build.gradle.kts中添加一个任务来打印路径：

tasks.register("printJarPath") {
    doLast {
        val jarTask = tasks.named("jar", Jar::class).get()
        println("JAR file will be generated at: ${jarTask.archiveFile.get().asFile.absolutePath}")
    }
}

运行gradlew printJarPath即可看到确切的输出路径。

3. Java CLI应用程序的最佳分发策略

将Java CLI应用程序分发给用户不仅仅是提供一个JAR文件那么简单。一个“裸”JAR文件通常需要用户手动配置Java运行时环境（JRE）和所有依赖项，这会带来诸多不便。以下是几种推荐的分发策略：

3.1 使用Gradle application插件生成的发布包

application插件是分发Java CLI应用程序的首选工具。它不仅能生成JAR包，还能创建包含所有依赖项和平台特定启动脚本（.bat for Windows, .sh for Linux/macOS）的发布压缩包。

• 生成发布包: 运行gradlew distZip（生成ZIP文件）或gradlew distTar（生成TAR文件）。
• 输出路径: 这些发布包通常位于build/distributions/目录下。
• 内容: 解压后，你会得到一个包含以下结构的目录：

  my-app/
  ├── bin/         # 包含启动脚本
  │   ├── my-app
  │   └── my-app.bat
  └── lib/         # 包含应用程序JAR和所有依赖JAR
      ├── my-app.jar
      ├── guava-30.1-jre.jar
      └── picocli-4.7.0.jar
      ...

  登录后复制
• 优点: 用户只需解压，然后直接运行bin/my-app（或bin/my-app.bat），无需手动处理依赖或JVM参数。

3.2 创建自包含可执行文件

对于希望提供更“原生”体验的用户，可以考虑创建自包含的可执行文件，这些文件不依赖于用户系统上预装的JRE。

• GraalVM Native Image: 使用GraalVM Native Image可以将Java应用程序编译成一个独立的本地可执行文件，无需JVM即可运行。这显著减小了分发包的大小，并提供了更快的启动速度。
  • 优点: 极快的启动速度，占用内存少，无需JVM。
  • 缺点: 编译时间长，对某些Java特性（如反射）支持有限，需要特定配置。
• JPackage (JDK 14+): JPackage工具（jpackage）可以将Java应用程序打包成平台特定的安装包（如.msi for Windows, .deb/.rpm for Linux, .dmg for macOS），这些包包含了私有的JRE副本。
  • 优点: 提供平台原生安装体验，包含JRE，用户无需单独安装Java。
  • 缺点: 生成的包较大，需要针对不同平台构建。

3.3 通过包管理器分发

对于更高级的场景，可以将应用程序发布到平台特定的包管理器中，例如：

• Homebrew (macOS): 创建一个Homebrew Formula。
• Scoop (Windows): 创建一个Scoop Manifest。
• APT/YUM (Linux): 创建.deb或.rpm包。

这种方式提供了最便捷的用户体验，但需要额外的配置和维护工作。

4. 总结与注意事项

• 确认输出路径: 在找不到JAR包时，首先检查你的项目结构（单项目 vs. 多项目）以及build.gradle.kts中application插件的配置。最直接的方法是查看构建日志或通过Gradle任务打印jar任务的archiveFile路径。
• 分发策略选择:
  • 对于大多数Java CLI应用，使用gradlew distZip/distTar生成的发布包是最推荐的入门级分发方式，它在便利性和易用性之间取得了很好的平衡。
  • 如果对启动速度和内存占用有极致要求，且不介意额外的构建复杂性，可以考虑GraalVM Native Image。
  • 如果需要提供平台原生安装体验，JPackage是一个很好的选择。
• 依赖管理: 无论采用哪种分发方式，确保所有运行时依赖都正确打包是关键。Gradle的application插件会自动处理这一点。

通过理解Gradle的构建机制和选择合适的分发策略，你可以确保你的Java CLI应用程序能够高效、便捷地交付给最终用户。

以上就是Gradlew Jar输出路径解析与Java CLI应用打包指南的详细内容，更多请关注php中文网其它相关文章！