Gradle的Zip任务是构建脚本里最常用的归档类型之一，它可以轻松地把一组文件打包成zip压缩包。不过在真实项目里，需求往往没那么简单：同一批源文件，可能需要分别放入压缩包内的多个不同目录，比如日志框架的配置文件既要出现在config目录下，又要以备份形式放到backup目录中。很多初学者在遇到这种需求时会直接堆叠多个into，结果发现文件不是丢了就是跑到意料之外的位置。这篇文章就来系统地讲清楚Zip任务中多目标路径配置的几种正确做法，并分析它们各自的适用场景。
为什么直接写多个into会出问题
先看一段典型的错误写法，很多问题都从这里开始：
task wrongZip(type: Zip) {
archiveFileName = "demo.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
from("src/main/config") {
into("config")
}
from("src/main/config") {
into("backup")
}
}表面上看，这段脚本声明了两次from，分别指向config和backup两个目标路径，似乎能实现一份文件进两个目录。实际上它确实能工作，但问题在于维护成本：如果源目录有十几个子目录，每个子目录都要进多个目标位置，脚本会迅速膨胀成几十行重复代码。更隐蔽的坑是，当from的内容和into的规则交织在一起时，文件的去向很难一眼看清，后续排查压缩包内容时会非常痛苦。
另一个常见误区是在同一个from块里写多个into，比如先into("config")再into("backup")。这种写法不会报错，但只有最后一个into会生效，前面的配置会被覆盖。因为into本质上是给当前CopySpec设置目标路径，而不是往一个列表里追加目标。理解了这一点，就能明白为什么多目标路径必须借助多个CopySpec或者其他手段来实现。
方案一：多个from块配合into实现分组归档
最直接也是最推荐的做法，就是为每一个目标路径单独声明一个from块。每个from都会生成一个独立的CopySpec，各自携带自己的into配置，互不干扰。来看一个完整的例子，把配置文件、脚本文件和文档分别放到压缩包的不同目录：
tasks.register("distZip", Zip) {
archiveFileName = "app-dist.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
// 配置文件同时进入两个目标路径
from("src/main/config") {
into("config")
}
from("src/main/config") {
into("backup/config")
}
// 启动脚本只进入 bin 目录
from("src/main/scripts") {
into("bin")
}
// 文档目录整体搬移
from("docs") {
into("docs")
}
}这种写法的核心思路是：目标路径的个数决定了from块的数量。虽然存在一定重复，但结构非常清晰，任何人读到这段脚本都能立刻知道哪个源进入了哪些目录。对于中小型项目，这种方式的可读性优势远大于重复带来的缺点。
如果担心源路径写重复，可以把它提取成变量或方法，让脚本保持整洁：
def configSrc = "src/main/config"
tasks.register("distZip", Zip) {
archiveFileName = "app-dist.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
from(configSrc) { into("config") }
from(configSrc) { into("backup/config") }
}需要注意的一点是，同一文件被复制到多个目标路径时，Gradle的增量构建机制会正确处理这种一对多关系，文件内容变化时任务会重新执行，不会出现某个目标路径漏更新的情况。
方案二：使用CopySpec复用与childrenSpecs嵌套
当目标路径组合变得复杂，比如同一份文件要进入三个以上的目录，纯靠堆from块就不太优雅了。这时可以利用CopySpec的嵌套特性，先定义一份可复用的规格，再挂到不同的into下面。
// 定义可复用的文件规格
def configSpec = copySpec {
from("src/main/config") {
exclude("*.bak")
}
}
tasks.register("nestedZip", Zip) {
archiveFileName = "app-nested.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
into("config") {
with(configSpec)
}
into("backup/config") {
with(configSpec)
}
into("archive/legacy-config") {
with(configSpec)
}
}这里的关键是with方法。它把一份CopySpec的内容合并进当前的into块中，从而实现一份定义、多处引用。与方案一相比，这种写法把源文件的过滤规则集中在一处，后续调整排除规则只需要改一个地方，符合单一职责原则。
此外，into本身返回的就是一个子CopySpec，所以你还可以在into块里继续嵌套into，构建出多层的目录结构。例如在config目录下再区分开发和生产环境的配置子目录，只需要在内层再用from加include过滤即可。这种组合能力是Copy任务家族共有的，Zip、Tar、Copy任务全都支持同样的语法，学一套就能到处用。
方案三：动态路径与多环境profile进阶用法
实际项目中还有一种场景：目标路径不是写死的，而是根据构建参数动态生成。比如通过-Penv=prod传入环境名，要求配置文件进入config/prod目录，脚本可以写成这样：
def env = project.findProperty("env") ?: "dev"
tasks.register("profileZip", Zip) {
archiveFileName = "app-${env}.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
from("src/config/${env}") {
into("config")
}
from("src/config/${env}") {
into("backup/${env}")
}
doLast {
println "已打包 ${env} 环境到 ${archiveFile.get()}"
}
}执行gradle profileZip -Penv=prod就能得到针对生产环境的压缩包，源目录和目标路径同时跟随参数变化。这种方式的灵活性很高，特别适合需要为多个客户或多个环境分别产出交付包的场景。
如果目标路径的列表本身就是动态的，比如要按模块名生成一组目录，可以借助eachDir或一个简单的循环来批量生成CopySpec：
tasks.register("modulesZip", Zip) {
archiveFileName = "modules.zip"
destinationDirectory = layout.buildDirectory.dir("dists")
file("modules").eachDir { modDir ->
from(modDir) {
into("modules/${modDir.name}")
}
from(modDir) {
into("mirror/${modDir.name}")
}
}
}这段脚本会遍历modules下的每个子目录，自动把每个模块的文件同时放进modules和mirror两组目录。新增模块时不需要改构建脚本，直接添加目录即可被自动纳入打包范围，非常适合模块数量经常变动的工程。
方案对比与选择建议
三种方案没有绝对优劣，选择时可以参考以下维度。方案一适合目标路径数量少、关系固定的场景，优点是直观，缺点是源路径声明会重复。方案二适合同一份文件要进入多个目录、且过滤规则需要统一维护的场景，优点是复用性强，缺点是嵌套层次多时调试稍麻烦。方案三适合路径需要随参数或目录结构动态变化的场景，灵活性最高，但脚本逻辑相对复杂，建议配合清晰的注释使用。
还有一个实践层面的建议：无论采用哪种方案，都建议在任务后面加一个校验步骤，比如用doLast打印压缩包内的文件清单，或者在CI流水线里解压校验关键路径是否存在。多目标路径配置是最容易出现文件放错位置的地方，一个简单的断言检查能在早期就暴露问题，避免交付包到了客户手里才发现目录结构不对。掌握这些技巧之后，Gradle的Zip任务基本可以覆盖日常打包工作中的所有路径定制需求。
Gradle Zip任务多目标路径构建脚本修改时间：2026-09-13 22:22:59