本文旨在解决gradle `zip` 任务在处理多个源文件到不同目标路径时的限制。通过引入并详细讲解gradle的 `distribution` 插件，我们将展示如何高效、灵活地为应用程序创建具有定制内部目录结构的zip分发包，同时满足特定的命名和输出路径要求，从而简化复杂的项目打包流程。
在Gradle项目中，当需要创建一个包含多种类型文件，并将其分别放置到ZIP包内不同子目录的发布包时，直接使用 Zip 任务可能会遇到挑战。Zip 任务的 into 方法通常只允许指定一个全局的目标路径，这使得为每个源文件或文件集合独立设置内部目标路径变得困难。
理解 Zip 任务的限制
考虑一个典型的项目结构，其中包含Java编译产物（JAR文件）和脚本文件，我们希望将它们打包成如下的ZIP文件：
myproject.zip
|-lib
| |-myapp.jar
\-bin
|-run.bat如果尝试使用 Zip 任务，如下所示：
tasks.register('dist', Zip) {
dependsOn('build')
from "build/libs/myapp.jar"
into "lib" // 第一次设置目标路径
from "src/main/scripts/run.bat"
into "bin" // 这将覆盖上一次的 "lib" 设置，导致所有文件都进入 "bin"
// ...
}如代码注释所示，into 方法会覆盖之前设置的目标路径，导致所有 from 指定的文件都进入最后一次 into 指定的目录，这无法满足将不同文件放入不同子目录的需求。
解决方案：利用 distribution 插件
Gradle的 distribution 插件专为构建和发布应用程序分发包而设计，它提供了更强大和灵活的方式来定义ZIP（或TAR）文件的内部结构。该插件通常与 application 插件一起使用，以更好地管理应用程序的启动脚本和依赖。
1. 引入插件
首先，在 build.gradle 文件中引入 java 和 application 插件（application 插件会自动应用 distribution 插件）：
plugins {
id 'java'
id 'application' // 引入application插件，它会间接引入distribution插件
}
group 'com.example'
version '1.0-SNAPSHOT'
repositories {
mavenCentral()
}
// 示例：如果你的myapp.jar是一个可执行应用，可以定义主类
application {
mainClassName = 'com.example.myapp.Main' // 替换为你的应用主类
}2. 配置分发包内容
distribution 插件通过 distributions 块来配置分发包。你可以在其中定义一个或多个分发，每个分发都可以指定其包含的内容以及在ZIP文件中的路径。
distributions {
main { // 定义一个名为 'main' 的分发
// 设置生成的ZIP/TAR文件的基础名称，例如 'myproject-1.0-SNAPSHOT.zip'
archiveBaseName.set('myproject')
// 通过 contents 块来定义分发包的内部结构
contents {
// 将编译生成的JAR文件放入 'lib' 目录
from(tasks.jar) { // tasks.jar 引用了java插件生成的jar任务的输出
into 'lib'
// 可选：如果生成的JAR名称不符合要求，可以重命名
rename { String fileName -> 'myapp.jar' }
}
// 将脚本文件放入 'bin' 目录
from("src/main/scripts/run.bat") {
into 'bin'
}
// 如果有其他依赖，application插件会自动将它们添加到 'lib' 目录
// 但如果需要额外添加非依赖文件，也可以在这里from
// from("path/to/extra/config.properties") {
// into 'config'
// }
}
}
}3. 定制输出文件名和目录
distribution 插件会自动创建 distZip 和 distTar 任务。默认情况下，它们会在 build/distributions 目录下生成名为 [archiveBaseName]-[version].zip 的文件。要满足将ZIP文件命名为 myproject.zip 并放置在 dist 目录下的要求，我们可以直接配置 distZip 任务：
// 配置 distZip 任务以定制输出文件名和目录
tasks.named('distZip', Zip) {
archiveFileName.set("myproject.zip") // 设置最终ZIP文件的名称
destinationDirectory.set(layout.buildDirectory.dir('dist')) // 设置ZIP文件的输出目录为 build/dist
}4. 构建分发包
配置完成后，执行 distZip 任务即可生成所需的ZIP分发包：
gradle distZip
执行成功后，你会在项目根目录下的 build/dist 目录中找到 myproject.zip 文件，其内部结构将严格按照 distributions 块中的定义。
完整 build.gradle 示例
plugins {
id 'java'
id 'application'
}
group 'com.example'
version '1.0-SNAPSHOT' // 项目版本号
repositories {
mavenCentral()
}
dependencies {
// 示例依赖，如果你的myapp.jar有外部依赖
// implementation 'org.slf4j:slf4j-api:1.7.30'
}
// 定义应用程序的主类，即使run.bat是主要入口，也建议为application插件设置
application {
mainClassName = 'com.example.myapp.Main' // 替换为你的应用程序主类
}
// 配置分发包
distributions {
main {
// 设置分发包的基础名称，例如生成的zip文件名为 myproject-1.0-SNAPSHOT.zip
archiveBaseName.set('myproject')
// 定义分发包的内部结构
contents {
// 将编译生成的JAR文件放入 'lib' 目录，并重命名为 myapp.jar
from(tasks.jar) {
into 'lib'
rename { String fileName -> 'myapp.jar' }
}
// 将脚本文件 src/main/scripts/run.bat 放入 'bin' 目录
from("src/main/scripts/run.bat") {
into 'bin'
}
// application插件会自动处理项目依赖并将其放入lib目录
// 如果有其他需要额外包含的文件，可以在这里添加
// from("src/main/resources/config.properties") {
// into 'conf'
// }
}
}
}
// 定制 distZip 任务的输出文件名和目录
tasks.named('distZip', Zip) {
archiveFileName.set("myproject.zip") // 最终ZIP文件的名称
destinationDirectory.set(layout.buildDirectory.dir('dist')) // 输出到 build/dist 目录
}总结
通过使用Gradle的 distribution 插件，我们可以轻松地克服 Zip 任务在处理多个源文件到不同目标路径时的局限性。distribution 插件提供了一种结构化且强大的方式来定义应用程序的分发包内容，包括将不同类型的文件放入指定的内部子目录。结合对 distZip 任务的额外配置，我们还可以完全控制生成ZIP文件的名称和输出位置，从而实现高度定制化的项目打包需求。这种方法不仅使得构建过程更加清晰和可维护，也更符合专业应用程序分发的最佳实践。
