本文旨在解决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）功能实现，具体步骤如下：
-
为插件模块创建独立的settings.gradle.kts
首先，在你的插件模块（例如my-gradle-plugin）的根目录下，创建一个空的settings.gradle.kts文件。这个文件虽然可以为空，但它的存在至关重要，它标志着my-gradle-plugin目录本身是一个独立的Gradle构建，而不是主构建的一个简单子项目。
+ root + my-gradle-plugin/ + build.gradle.kts + settings.gradle.kts // <-- 新增此文件 -
在根settings.gradle.kts中使用includeBuild()
在项目的根settings.gradle.kts文件中，通过pluginManagement块内的includeBuild()方法来引入插件模块。这会将插件模块作为一个复合构建的一部分，指示Gradle在解析插件时，首先考虑这个内部构建提供的插件。
修改后的根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仓库的繁琐步骤，直接在项目内部实现了插件的构建和消费闭环。
