本文详细介绍了在Gradle多模块项目中，如何解决子模块无法识别和使用同一项目中定义的插件的问题。核心解决方案是利用Gradle的复合构建（Composite Builds）机制，通过在根项目的`settings.gradle.kts`文件中使用`includeBuild()`指令，将插件模块作为内部构建引入。这使得Gradle能够直接从源代码构建并解析插件，避免了需要将插件发布到外部仓库的麻烦，从而实现了插件在项目内部的无缝集成和消费。
在现代软件开发中，Gradle多模块项目结构因其模块化、可重用性等优势而被广泛采用。然而，当项目内部包含一个自定义Gradle插件，并且希望该插件能被同一项目中的其他模块直接消费时，开发者可能会遇到插件无法被识别和解析的问题。本文将深入探讨这一挑战，并提供一个基于Gradle复合构建的专业解决方案。
理解问题：插件未找到
在一个典型的多模块Gradle项目中，如果一个模块（例如my-implementation）尝试应用同一项目中定义的另一个模块（例如my-gradle-plugin）提供的插件，Gradle通常会默认尝试从预配置的插件仓库（如Gradle Plugin Portal、Maven Central、Maven Local等）解析该插件。
例如，当my-implementation模块的build.gradle.kts中包含以下配置时：
plugins {
id("org.my.gradle.plugin") version "internal" // "internal"在此处仅为占位符
}如果my-gradle-plugin模块没有被正确地构建并发布到这些仓库中，或者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无法在任何配置的插件源中找到org.my.gradle.plugin。这是因为Gradle将内部插件视为外部依赖，而没有意识到它可以在当前构建中生成并使用该插件。
解决方案：利用复合构建（Composite Builds）
Gradle的复合构建功能允许将多个独立的Gradle构建组合成一个更大的构建。通过这种方式，主构建可以“包含”其他构建，并直接从它们的源代码中解析依赖项或插件，而无需进行发布。
要解决上述问题，核心思路是将my-gradle-plugin模块声明为一个被主构建“包含”的构建。这通过在根项目的settings.gradle.kts文件中使用includeBuild()指令来实现。
1、架构轻盈，完全免费与开源采用轻量MVC架构开发，兼顾效率与拓展性。全局高效缓存，打造飞速体验。 2、让简洁与强大并存强大字段自定义功能，完善的后台开关模块，不会编程也能搭建各类网站系统。 3、顶级搜索引擎优化功能纯静态、伪静态，全部支持自由设置规则，内容、栏目自由设置URL格式。 4、会员、留言、投稿、支付购物神马一个不能少不断升级完善的模块与插件，灵活的组装与自定义设置，满足你的多样需求。
步骤一：配置根项目的 settings.gradle.kts
在项目的根目录下的settings.gradle.kts文件中，添加includeBuild("my-gradle-plugin")指令。这会告诉Gradle，my-gradle-plugin是一个独立的构建，其输出（包括插件）应该在当前构建中可用。
同时，在pluginManagement块中，需要配置插件仓库和解析策略。特别是，resolutionStrategy允许我们为内部插件指定版本，确保Gradle能够将org.my.gradle.plugin的请求映射到当前项目的版本。
// ./root/settings.gradle.kts
rootProject.name = "root-project"
// 包含其他子模块
include("my-api", "my-implementation")
pluginManagement {
// 关键步骤：将插件模块作为包含构建引入
includeBuild("my-gradle-plugin")
repositories {
mavenLocal()
maven { url = uri("https://xyz") } // 你的私有Maven仓库
gradlePluginPortal()
mavenCentral()
}
resolutionStrategy {
// 获取根项目的版本号
val version: String by settings
eachPlugin {
// 当请求的插件ID是"org.my.gradle.plugin"时，使用当前项目的版本
if (requested.id.id == "org.my.gradle.plugin") {
useVersion(version)
}
}
}
}步骤二：插件模块的 build.gradle.kts 配置
my-gradle-plugin模块的build.gradle.kts需要正确配置以声明它是一个Gradle插件。这通常涉及应用java-gradle-plugin和maven-publish插件，并定义插件的ID、实现类和版本。
// ./root/my-gradle-plugin/build.gradle.kts
plugins {
`java-gradle-plugin` // 声明这是一个Gradle插件项目
`maven-publish` // 用于发布插件（即使是内部使用，也有助于元数据生成）
}
gradlePlugin {
plugins {
create("myGradlePlugin") { // 创建一个插件定义
id = "org.my.gradle.plugin"
group = "org.my.gradle.plugin"
implementationClass = "org.my.gradle.plugin.MyGradlePlugin" // 插件的实现类
version = project.version // 使用项目版本
}
}
}步骤三：在消费模块中应用插件
一旦根项目的settings.gradle.kts配置完成，my-implementation模块就可以像使用任何其他插件一样，直接应用内部插件了：
// ./root/my-implementation/build.gradle.kts
plugins {
// 插件ID和版本，版本将通过settings.gradle.kts中的resolutionStrategy解析
id("org.my.gradle.plugin") version "internal"
}这里的version "internal"是一个约定俗成的占位符，实际的版本解析由根settings.gradle.kts中的resolutionStrategy负责，它会将org.my.gradle.plugin映射到根项目定义的版本（例如0.0.3-SNAPSHOT）。
工作原理
通过includeBuild("my-gradle-plugin")，Gradle被告知my-gradle-plugin是一个内部构建。当my-implementation模块请求org.my.gradle.plugin时，Gradle首先会在当前构建的包含构建中查找该插件，而不是直接去远程仓库。由于my-gradle-plugin已经被声明为包含构建，Gradle会负责构建它，并使其生成的插件元数据和类路径在主构建中可用，从而解决了“插件未找到”的问题。
注意事项
- Gradle版本： 本文所述的解决方案在Gradle 7.5及更高版本中验证通过。对于更旧的Gradle版本，可能需要查阅相应版本的官方文档以确认兼容性。
- 版本管理： settings.gradle.kts中的resolutionStrategy是确保插件版本正确解析的关键。它允许你集中管理内部插件的版本，使其与主项目的版本保持一致。
- 插件模块的构建： 确保my-gradle-plugin模块本身能够独立构建成功，并且正确地应用了java-gradle-plugin，这是生成Gradle插件所需元数据和类文件的基础。
-
插件的实现： 插件的实现类（如org.my.gradle.plugin.MyGradlePlugin）必须存在于my-gradle-plugin模块中，并正确实现Plugin
接口。
总结
在Gradle多模块项目中内部构建和消费插件，是一个常见的需求。通过巧妙地利用Gradle的复合构建机制，特别是在根settings.gradle.kts中引入includeBuild()指令，我们可以有效地解决插件解析问题，实现插件在项目内部的无缝集成。这种方法不仅简化了开发工作流，避免了不必要的插件发布步骤，还提高了项目的内聚性和可维护性。掌握这一技巧，将使您在管理复杂的Gradle项目时更加得心应手。
