在Gradle多项目构建中，开发Java命令行应用程序时，开发者常遇到`gradlew jar`命令执行成功但找不到JAR包的问题。本教程旨在阐明在多项目结构下，JAR包的实际输出位置通常位于特定应用子项目的`build/libs`目录，例如`app/build/libs`。同时，文章还将探讨分发Java CLI应用的最佳实践，包括使用Gradle的发行版任务，以提供更完整的用户体验。
理解Gradle项目结构与JAR包输出
在使用Gradle构建Java命令行界面（CLI）应用程序时，一个常见的困惑是执行gradlew jar任务后，预期的JAR文件似乎没有生成在根项目的build/libs目录下。这通常发生在项目采用了多模块（或多项目）结构时。
单项目与多项目构建的区别
- 单项目构建： 如果您的build.gradle.kts文件位于项目根目录，并且没有定义任何子项目，那么由application插件生成的JAR文件通常会位于根项目的build/libs目录下。
-
多项目构建： 在多项目结构中，项目被划分为多个独立的模块（子项目），每个子项目都有自己的build.gradle.kts文件和独立的构建目录。例如，一个常见的结构可能是：
root/ ├── build.gradle.kts (根项目配置) ├── settings.gradle.kts (定义子项目) └── app/ ├── build.gradle.kts (应用子项目配置) └── src/main/java/...在这种情况下，如果application插件应用于app子项目，那么由该子项目生成的JAR文件将位于app/build/libs目录下，而不是根项目的build/libs。
定位JAR文件的正确路径
当您在多项目结构中运行gradlew jar时，Gradle会为每个应用了application插件的子项目生成JAR文件。如果您的主应用程序逻辑位于名为app的子项目中，那么您应该在./app/build/libs路径下查找生成的JAR文件。
立即学习“Java免费学习笔记（深入）”；
例如，考虑以下build.gradle.kts配置，它可能存在于您的app子项目中（或者根项目配置中指定了app子项目作为主应用模块）：
plugins {
// 应用application插件以支持构建Java CLI应用程序
application
id("com.diffplug.spotless") version "6.12.0" // 示例插件
}
repositories {
mavenCentral()
}
dependencies {
// 应用程序依赖
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")
// 测试依赖
testImplementation("junit:junit:4.13.2")
}
application {
// 定义应用程序的主类
mainClass.set("testlauncher.command.Runner")
}
// 注意：如果subprojects块在根项目的build.gradle.kts中，
// 它会应用于所有子项目。这里为简化，假设它与application插件在同一项目。
spotless {
java {
importOrder()
removeUnusedImports()
googleJavaFormat()
}
}
// 示例：确保build任务依赖spotlessApply
// project.tasks.findByName("build")?.dependsOn(project.tasks.findByName("spotlessApply"))在上述配置中，application插件被应用，并且mainClass被设置。如果这个build.gradle.kts文件属于一个名为app的子项目，那么执行gradlew :app:jar（或者在根目录执行gradlew jar，Gradle会自动为子项目执行）后，生成的JAR文件将位于./app/build/libs目录下。
Java CLI应用的分发策略
仅仅提供一个JAR文件给用户下载并非分发Java CLI应用的最佳方式，尽管它在某些简单场景下可行。主要原因是用户需要自行确保其系统上安装了兼容的Java运行时环境（JRE），并且知道如何通过java -jar your-app.jar命令来执行。为了提供更友好的用户体验，Gradle的application插件提供了更强大的分发机制。
1. 使用Gradle的发行版任务
application插件自动为您的应用程序添加了几个有用的任务，用于创建完整的发行版：
-
installDist： 将应用程序及其所有运行时依赖项复制到一个本地目录（通常是build/install/
）。这个目录包含启动脚本（Windows批处理文件和Unix shell脚本），用户可以直接运行这些脚本而无需手动调用java -jar。 - distZip / distTar： 打包installDist任务生成的内容到一个ZIP或TAR归档文件中。这些归档文件包含了应用程序、所有依赖项和启动脚本，用户下载后解压即可使用。
示例：创建发行版
您可以通过运行以下命令来生成一个包含所有必要文件的发行版：
gradlew distZip # 或者 gradlew distTar
执行这些命令后，您将在./app/build/distributions（如果app是子项目）或./build/distributions（如果application插件应用于根项目）目录下找到your-app-name.zip和your-app-name.tar文件。这些文件是推荐的分发方式，因为它们提供了：
- 易于启动： 包含平台特定的启动脚本。
- 依赖管理： 自动捆绑所有运行时依赖项。
- 版本控制： 归档文件通常包含版本信息。
2. 考虑GraalVM Native Image
对于追求极致用户体验和性能的场景，您可以考虑使用GraalVM Native Image技术。它可以将您的Java应用程序编译成一个独立的、平台特定的本地可执行文件，无需外部JVM即可运行。这消除了用户对Java环境的依赖，提供了类似C/C++应用程序的启动速度和内存占用。
要实现这一点，您通常需要：
- 安装GraalVM。
- 在Gradle配置中集成GraalVM Native Build Tools插件。
- 配置Native Image构建任务。
这是一个更高级的选项，但对于希望将Java CLI应用程序作为真正独立的二进制文件分发的情况非常有效。
总结与注意事项
- 定位JAR文件： 在Gradle多项目构建中，由application插件生成的JAR文件通常位于应用子项目的build/libs目录下（例如，./app/build/libs）。始终检查您期望生成JAR的模块的build/libs目录。
- 分发策略： 避免直接分发原始JAR文件。推荐使用Gradle的distZip或distTar任务来创建完整的发行版，这些发行版包含启动脚本和所有依赖项，为用户提供更便捷的体验。
- 高级分发： 对于需要独立于JVM运行的应用程序，可以探索GraalVM Native Image技术。
- 调试构建： 如果您仍然无法找到JAR文件或遇到其他构建问题，可以使用gradlew tasks --all查看所有可用的任务，或使用gradlew jar --info或gradlew jar --debug获取更详细的构建日志，帮助您诊断问题。
通过理解Gradle的项目结构和利用其提供的分发工具，您可以有效地构建和分发您的Java CLI应用程序，为用户提供专业且易于使用的产品。
