Gradle多模块项目：构建与消费内部插件的实战指南

本文旨在解决gradle多模块项目中，内部开发的插件无法被同项目其他模块识别和使用的问题。通过引入gradle的复合构建（composite builds）机制，特别是利用`includebuild()`在根`settings.gradle.kts`中声明插件模块，并为插件模块配置独立的`settings.gradle.kts`文件，确保gradle能够正确地构建并解析内部插件，从而实现插件的顺畅消费。

问题概述：多模块项目中的插件未找到

在复杂的Gradle多模块项目中，开发者常会创建自定义插件来封装通用配置或业务逻辑。然而，当尝试在同一个多模块项目中的其他模块（例如my-implementation）中应用这些内部插件（例如my-gradle-plugin）时，Gradle可能会报告“Plugin was not found”的错误。

典型的错误信息如下：

* What went wrong:
Plugin [id: 'org.my.gradle.plugin', version: '0.0.3-SNAPSHOT'] was not found in any of the following sources:

- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (could not resolve plugin artifact 'org.my.gradle.plugin:org.my.gradle.plugin.gradle.plugin:0.0.3-SNAPSHOT')
  Searched in the following repositories:
    MavenLocal(file:/home/jenkins/.m2/repository/)
    maven(https://xyz)
    Gradle Central Plugin Repository
    MavenRepo

这个错误表明Gradle在配置的插件仓库中（包括本地Maven仓库、远程Maven仓库和Gradle插件门户）未能找到对应的插件构件。尽管在根settings.gradle.kts的pluginManagement中已经配置了mavenLocal()和其他仓库，并且通过resolutionStrategy指定了版本，但Gradle似乎并未意识到需要先构建项目内部的my-gradle-plugin模块，然后才能使用它。

解决方案核心：利用复合构建（Composite Builds）

解决此问题的关键在于明确告诉Gradle，my-gradle-plugin模块是一个独立的构建，其产物（即插件）需要在主构建的早期阶段被解析和使用。这可以通过Gradle的复合构建（Composite Builds）功能实现，具体步骤如下：

1. 为插件模块创建独立的settings.gradle.kts

   首先，在你的插件模块（例如my-gradle-plugin）的根目录下，创建一个空的settings.gradle.kts文件。这个文件虽然可以为空，但它的存在至关重要，它标志着my-gradle-plugin目录本身是一个独立的Gradle构建，而不是主构建的一个简单子项目。

   + root
     + my-gradle-plugin/
       + build.gradle.kts
       + settings.gradle.kts // <-- 新增此文件

   登录后复制

2. 在根settings.gradle.kts中使用includeBuild()

   在项目的根settings.gradle.kts文件中，通过pluginManagement块内的includeBuild()方法来引入插件模块。这会将插件模块作为一个复合构建的一部分，指示Gradle在解析插件时，首先考虑这个内部构建提供的插件。

   

   Logomaster.ai

   Logo在线生成工具

   99

   查看详情

   修改后的根settings.gradle.kts示例如下：

   // ./root/settings.gradle.kts
   
   rootProject.name = "root-project"
   
   // 包含其他子项目
   include("my-api", "my-implementation")
   
   pluginManagement {
       // 使用 includeBuild() 声明插件模块为一个独立的构建
       // Gradle 会在解析插件时，优先从这个构建中查找
       includeBuild("my-gradle-plugin")
   
       repositories {
           mavenLocal()
           maven { url = uri("https://xyz") }
           gradlePluginPortal()
           mavenCentral()
       }
       resolutionStrategy {
           val version: String by settings
           eachPlugin {
               // 如果请求的插件ID与内部插件匹配，则使用当前项目版本
               if (requested.id.id == "org.my.gradle.plugin") {
                   useVersion(version)
               }
           }
       }
   }

   登录后复制

   解释：

   • includeBuild("my-gradle-plugin")：告诉Gradle将my-gradle-plugin目录视为一个独立的构建，并且其提供的插件应该在主构建的插件解析阶段可用。
   • resolutionStrategy：此部分确保了当其他模块请求org.my.gradle.plugin时，会使用在根gradle.properties中定义的项目版本（例如0.0.3-SNAPSHOT）。

插件的消费方式

完成上述配置后，其他模块就可以像使用任何外部插件一样，在它们的build.gradle.kts文件中应用内部插件了。

// ./my-implementation/build.gradle.kts

plugins {
   // 当使用 includeBuild() 引入内部插件时，
   // 推荐使用 "internal" 作为版本，这是一种约定，表示插件来自当前构建环境
   id("org.my.gradle.plugin") version "internal"
}

注意事项：

• 版本号 internal： 在复合构建中，为通过includeBuild()引入的插件指定版本时，通常使用一个特殊的值，例如"internal"。这并非实际的版本号，而是一种约定，表明该插件是从当前构建的“内部”来源获取的，而不是从外部仓库下载。Gradle在解析时，会根据includeBuild的声明找到正确的插件。
• Gradle版本兼容性： 这种复合构建的插件解析机制在Gradle 7.5+版本中经过验证可行。对于更早的Gradle版本，行为可能有所不同，建议查阅对应版本的官方文档。

工作原理与总结

通过在插件模块中添加一个空的settings.gradle.kts文件，并修改根settings.gradle.kts以includeBuild("my-gradle-plugin")，我们有效地将插件模块提升为一个独立的“复合构建”。Gradle在执行主构建时，会首先处理这个复合构建，确保插件能够被编译和打包。随后，当主构建中的其他模块尝试解析org.my.gradle.plugin时，Gradle会知道去这个内部复合构建中查找，而不是仅仅依赖外部插件仓库。

这种方法使得在大型多模块项目中管理和消费内部开发的Gradle插件变得更加无缝，极大地简化了开发和测试流程。它避免了将内部插件发布到本地Maven仓库的繁琐步骤，直接在项目内部实现了插件的构建和消费闭环。

以上就是Gradle多模块项目：构建与消费内部插件的实战指南的详细内容，更多请关注php中文网其它相关文章！