第1步：理解目标场景与多项目结构
同级项目的概念与需求
在一个 Gradle 多项目构建 中，所谓的“同级项目”指的是同一个根项目下的其他子模块。对于某些场景，我们需要让 同级项目的 JAR 自动复制 到一个统一的目标路径，方便后续的引用或外部使用。这种需求属于 Gradle 实战 的典型用例，其核心在于用一个 Copy 任务把产出的 JAR 文件从各子模块转移到指定位置。
实现该目标的关键是：在根项目（或指定聚合模块）中，直接读取 其他子项目的 jar 产出路径，并通过一个明确的 目标路径 将产物统一拷贝过去，从而实现 自动化与可重复性。
实现目标的核心思路
核心思路是通过一个 Copy 任务，将同级子项目的 jar 产出作为输入来源，拷贝到你指定的 目标路径。为了确保构建幂等性，拷贝过程应依赖于子模块的 jar 任务输出，而不是在构建阶段动态创建文件。
在设计时要考虑的要点包括：可扩展性（支持新增同级模块）、路径规范（目标路径统一清晰）、以及 构建触发时机（让拷贝在合适的阶段执行）。
第2步：准备工作与多项目结构配置
项目结构示例与分模块策略
常见的多项目结构是根目录下包含 app、libA、libB 等子模块，均使用 Java/Gradle 插件产出 jar 文件。为了实现 同级项目的 JAR 自动复制，需要一个清晰的模块划分与统一的设置入口。
在根目录下实现一个集中式的拷贝逻辑，可以将 同级模块名单和它们的 jar 产出路径绑定到一个 Copy 任务中，从而实现一次配置，多次复用的效果。
settings.gradle 配置要点
settings.gradle 负责把需要参与构建的子模块注册进来，这是实现“同级项目”的前提。确保包含的子模块与实际目录结构一致，且都能生成 jar 文件。
// settings.gradle
rootProject.name = 'multi-project-demo'
include ':app', ':libA', ':libB'通过上述配置，根项目就可以对 libA 与 libB 等同级子模块进行引用和产物访问，从而实现自动化拷贝。
Root 与子项的插件与依赖基础
确保各子项都应用了 java 插件，以便生成 jar 文件；根项目应具备对这些子项的引用能力，以便在 Copy 任务中引用它们的产出。此处的重点在于让整个流程在 Gradle 构建生命周期内可预测地执行。
第3步：实现复制逻辑与自动化流程
获取同级项目的 JAR 路径
核心在于从 子模块的 jar 任务获取产出的 archiveFile 路径，并将其作为 Copy 任务的输入。这样可确保无论同级模块数量如何变化，都会自动识别产物并进行拷贝。
重要：使用 archiveFile.get().asFile 的方式获取文件对象，兼容 Gradle 6.x 及以上版本，并且确保在配置阶段就解析好路径。
实现 Copy 任务
// 根项目 build.gradle（Groovy DSL）
def siblingJars = [project(':libA').tasks.named('jar').get().archiveFile.get().asFile,project(':libB').tasks.named('jar').get().archiveFile.get().asFile
]tasks.register('copySiblingJars', Copy) {description = 'Copy jars from sibling projects to a designated directory'into "$rootDir/external_jars"from siblingJars
}
通过上面的实现，libA、libB 的 JAR 将被拷贝到 root/external_jars 目录，形成一个统一的产物聚集地，利于后续引用与部署。
自动化触发与构建集成
// 根项目 build.gradle
tasks.named('build') {dependsOn 'copySiblingJars'
}
将 copySiblingJars 设为 build 的依赖，确保在每次构建完成后，同级项目的 JAR 自动复制 的流程都会执行，从而实现端到端的自动化。
第4步：注意事项与最佳实践
兼容性与版本注意
不同版本的 Gradle 对于 archiveFile 的访问方式略有差异，推荐使用 archiveFile.get().asFile 的写法以提升向后兼容性，尤其在 Gradle 6.x 及以上版本中效果最佳。
若你仍在使用较老版本的 Gradle，可以考虑临时回退到 archivePath，但应计划尽快迁移到 archiveFile 的新 API，以保持未来的兼容性。
缓存、幂等与执行时机
Copy 任务应具备幂等性：如果目标路径已有相同的 JAR，且未发生变更，Gradle 会避免重复拷贝。确保 Copy 的输入来自 jar 任务的产出路径，使得只有在相关产物变化时才触发实际拷贝。
为避免子模块尚未编译就执行拷贝的情况，确保 Copy 任务的依赖关系明确，且在 构建流程中合理排序，使 jar 任务先完成，再执行拷贝。
路径选择与权限管理
目标路径应在本地或网络共享环境下具备可写权限，并且要有统一的路径约束，例如 ${rootDir}/external_jars 作为默认入口，减少跨环境的差异。
在团队协作中，建议将路径规范化并加入到 .gitignore，避免产物被意外提交，确保仓库的干净与可重复构建。
第5步：常见问题与排错要点
如果同级 JAR 名称或数量发生变化
上面的实现通过直接读取子模块的 jar 产出，对数量和名称变化具有一定的容错性。若需要更严格的校验，可以在 Copy 任务前添加对 siblingJars 的存在性与后缀校验。
def jarFiles = [project(':libA').tasks.named('jar').get().archiveFile.get().asFile,project(':libB').tasks.named('jar').get().archiveFile.get().asFile
]
jarFiles.each { assert it.exists() && it.name.endsWith('.jar') }
如果某些子模块尚未编译就执行拷贝
为了避免拷贝阶段拿到空缺产物，可以在构建流程中严格设定依赖顺序，确保 jar 任务先执行，然后再触发拷贝，或者将拷贝任务的执行放在特定阶段（如 assemble 之后）进行。
日志与调试的实用技巧
在复杂场景下，开启调试日志有助于定位问题，例如输出拷贝源和目标路径、以及每个输入文件的存在性信息。使用 Gradle 的 --info/--debug 级别来获取更详细的执行信息。
通过以上步骤，你可以实现 Gradle 实战 的场景：如何把同级项目的 JAR 自动复制到指定路径，并在构建过程中自动更新目标目录中的产物，确保团队在多项目构建中的产物管理更加高效、可控。证据性地，本文中给出的配置与代码示例均集中于实现同级项目的 JAR 自动复制的核心流程，能够快速落地到现实项目中。若后续需要扩展，可以将更多子模块纳入 siblingJars 的集合，逐步提升自动化覆盖范围。
