在Gradle多模块项目中，当插件模块与消费它的模块位于同一构建中时，可能会遇到插件无法解析的问题。本文将详细介绍如何通过利用Gradle的复合构建（Composite Builds）特性，特别是使用`includeBuild()`指令，来正确地构建和消费内部插件。核心在于为插件模块创建独立的`settings.gradle.kts`文件，并将其作为独立构建引入主项目的`settings.gradle.kts`中，从而确保插件在被其他模块引用前能够被正确构建和解析。
理解多模块项目中的插件解析挑战
在大型Gradle项目中，通常会将功能划分为多个模块，其中可能包含一个或多个自定义Gradle插件。当这些插件作为项目内部的一部分，而非发布到外部仓库时，Gradle在解析它们时会遇到挑战。标准的插件应用方式，如plugins { id("org.my.gradle.plugin") version "internal" }，会指示Gradle从配置的插件仓库（如Gradle Plugin Portal、MavenLocal等）查找插件。然而，如果插件本身是当前多模块构建的一部分，Gradle并不会自动知道它需要先构建这个内部插件模块，然后再尝试解析它。
这通常会导致以下错误信息：
* 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无法在任何配置的仓库中找到插件，因为它没有将其视为一个需要先构建的本地组件。
解决方案：利用复合构建（Composite Builds）
解决此问题的关键在于使用Gradle的复合构建（Composite Builds）功能。复合构建允许您将独立的Gradle构建组合到一个更大的构建中。在这种场景下，我们可以将内部插件模块视为一个独立的构建，并将其“包含”到主构建中。
要实现这一点，需要两个核心步骤：
- 为插件模块创建独立的settings.gradle.kts文件。
- 在主项目的settings.gradle.kts中使用includeBuild()指令引入插件模块。
1. 插件模块的独立配置
首先，确保您的Gradle插件模块（例如my-gradle-plugin）具有以下结构和配置：
my-gradle-plugin/build.gradle.kts:
plugins {
`java-gradle-plugin` // 声明这是一个Gradle插件项目
`maven-publish` // 用于发布插件，即使是内部使用也推荐配置
}
gradlePlugin {
plugins {
create("org.my.gradle.plugin") {
id = "org.my.gradle.plugin"
group = "org.my.gradle.plugin"
implementationClass = "org.my.gradle.plugin.MyGradlePlugin"
version = project.version // 使用项目版本
}
}
}
// 其他依赖或配置
dependencies {
// 例如：implementation(gradleApi())
// implementation(localGroovy())
}my-gradle-plugin/settings.gradle.kts: 这是最关键的一步。在插件模块的根目录下创建一个空的settings.gradle.kts文件。这个文件将把my-gradle-plugin模块声明为一个独立的Gradle构建，使其可以被其他构建包含。
// my-gradle-plugin/settings.gradle.kts // 这个文件可以是空的，但它的存在至关重要
2. 主项目中的includeBuild()配置
接下来，在主项目的settings.gradle.kts文件中，您需要使用includeBuild()指令来告诉Gradle，my-gradle-plugin是一个需要被包含进来的独立构建。
root/settings.gradle.kts:
rootProject.name = "root-project"
// 包含其他子模块
include("my-api", "my-implementation")
pluginManagement {
// 关键一步：将插件模块作为复合构建引入
// Gradle会先构建这个包含的构建，然后才能解析其中的插件
includeBuild("my-gradle-plugin")
repositories {
mavenLocal()
maven { url = uri("https://xyz") } // 您的私有仓库
gradlePluginPortal()
mavenCentral()
}
resolutionStrategy {
// 定义插件的解析策略
val version: String by settings // 从settings.gradle.kts获取版本
eachPlugin {
// 如果请求的插件ID是"org.my.gradle.plugin"，则使用项目定义的版本
if (requested.id.id == "org.my.gradle.plugin") {
useVersion(version)
}
}
}
}在pluginManagement块中，includeBuild("my-gradle-plugin")指令会指示Gradle在尝试解析插件之前，先处理my-gradle-plugin目录下的构建。这样，当my-implementation模块尝试应用org.my.gradle.plugin时，Gradle已经知道如何找到并使用它。
resolutionStrategy块是可选但推荐的，它允许您为内部插件指定版本，确保所有模块都使用相同的内部插件版本，通常是从主项目的gradle.properties或settings.gradle.kts中定义的版本。
消费内部插件
完成上述配置后，您就可以在项目的任何模块中像使用外部插件一样消费这个内部插件了，无需担心解析问题。
my-implementation/build.gradle.kts:
plugins {
id("org.my.gradle.plugin") version "internal" // 这里的"internal"可以是任何字符串，因为版本由resolutionStrategy控制
}
// 模块的其他配置请注意，version "internal"在这里的实际作用不大，因为resolutionStrategy已经强制了插件版本。您可以将其设置为任何字符串，或者如果resolutionStrategy足够精确，甚至可以省略版本声明，但通常为了清晰性会保留。
注意事项与总结
- Gradle版本兼容性： 这种复合构建和includeBuild()的用法在Gradle 7.5+版本中得到了很好的支持和测试。对于更老的Gradle版本，行为可能有所不同，建议查阅对应版本的官方文档。
- settings.gradle.kts的重要性： 插件模块内部的空settings.gradle.kts文件是实现这一方案的关键。它将该目录提升为一个独立的Gradle构建，从而可以被主构建通过includeBuild()包含。
- 插件版本管理： 推荐在主项目的settings.gradle.kts中使用resolutionStrategy来统一管理内部插件的版本，避免版本冲突和不一致。
- 官方文档： Gradle官方文档在“Composite Builds”章节提供了更详细的信息和最佳实践，特别是关于“Included Plugin Builds”的部分，是深入理解此机制的宝贵资源。
通过上述步骤，您可以在Gradle多模块项目中无缝地构建和消费内部插件，极大地简化了开发工作流，并确保了插件的正确解析和应用。
