本文详细阐述了在gradle多模块项目中构建和消费内部插件的策略。当插件作为项目内部模块存在时，gradle可能无法在构建其他模块之前发现并构建该插件。解决方案是利用gradle的复合构建（composite builds）特性，通过在根目录的`settings.gradle.kts`文件中使用`includebuild()`指令，强制gradle首先构建插件模块，并确保插件模块拥有独立的`settings.gradle.kts`文件。结合适当的插件版本解析策略，可以实现在同一仓库内无缝集成和使用内部插件。
理解多模块项目中的Gradle插件发现挑战
在复杂的软件项目中，将自定义的Gradle插件作为多模块项目的一部分进行开发和管理是一种常见需求。例如，一个库可能需要特定的构建配置，而这些配置可以通过一个内部开发的Gradle插件来自动化。然而，当尝试在同一多模块项目中的其他模块（例如my-implementation）中应用这个内部插件（my-gradle-plugin）时，开发者常常会遇到“插件未找到”的错误：
Plugin [id: 'org.my.gradle.plugin', version: '0.0.3-SNAPSHOT'] was not found in any of the following sources: ...
这个问题的核心在于Gradle在解析插件依赖时，默认情况下并不知道项目内部的插件模块需要首先被构建并发布（即使是本地发布）才能被其他模块使用。Gradle的插件解析机制通常会首先查找核心插件、插件门户（Gradle Plugin Portal）或配置的Maven/Ivy仓库。如果插件尚未被构建并存在于这些可解析的源中，就会导致上述错误。
解决方案核心：复合构建（Composite Builds）与includeBuild()
解决此问题的关键在于利用Gradle的复合构建（Composite Builds）特性。复合构建允许将独立的Gradle构建组合在一起，形成一个更大的、协同工作的构建。通过这种方式，我们可以将内部插件模块视为一个独立的构建，并将其“包含”到主构建中，从而强制Gradle在主构建开始解析依赖之前，先构建并使其插件可用。
要实现这一点，需要两个关键步骤：
为插件模块创建独立的settings.gradle.kts文件： 为了让Gradle将插件模块视为一个独立的构建，该模块内部必须包含自己的settings.gradle.kts文件（即使是空的）。这个文件标志着该目录是一个独立的Gradle构建根目录，从而将其与主项目的构建分离。
在根项目的settings.gradle.kts中使用includeBuild()： 在主项目的settings.gradle.kts文件中，使用pluginManagement { includeBuild("path/to/plugin-module") }指令。这会告诉Gradle：在解析插件依赖时，请首先考虑这个被包含的构建。Gradle会确保这个被包含的构建（即我们的插件模块）首先被构建，并且其提供的插件能够被主构建的其他模块发现和使用。
实施步骤：配置settings.gradle.kts
假设项目结构如下：
+ root
+ my-api/
+ my-implementation/
+ my-gradle-plugin/
+ build.gradle.kts
+ settings.gradle.kts // <-- 新增或确保存在
+ build.gradle.kts
+ gradle.properties
+ settings.gradle.kts-
插件模块的build.gradle.kts配置： my-gradle-plugin/build.gradle.kts文件应包含标准的Gradle插件配置，例如：
// my-gradle-plugin/build.gradle.kts plugins { `java-gradle-plugin` `maven-publish` // 如果需要发布到本地或远程仓库 } gradlePlugin { plugins { create("myPluginId") { id = "org.my.gradle.plugin" group = "org.my.gradle.plugin" implementationClass = "org.my.gradle.plugin.MyGradlePlugin" version = project.version // 使用项目版本 } } } group = "org.my.gradle.plugin" version = project.version -
根项目的settings.gradle.kts配置： 这是最关键的配置。在根项目的settings.gradle.kts中，除了包含常规模块外，还需要在pluginManagement块中添加includeBuild("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 { if (requested.id.id == "org.my.gradle.plugin") { useVersion(version) } } } }请注意，gradle.properties文件中应定义项目版本，例如：version=0.0.3-SNAPSHOT。resolutionStrategy中的val version: String by settings会从gradle.properties中读取这个版本。
-
插件模块内部的settings.gradle.kts： 在my-gradle-plugin/目录下创建一个（或确保存在）settings.gradle.kts文件。这个文件可以为空，它的存在本身就是关键。
// my-gradle-plugin/settings.gradle.kts // 这个文件可以为空，但必须存在，以将其标记为独立的构建
应用插件
完成上述配置后，在任何需要使用该插件的模块（例如my-implementation）的build.gradle.kts文件中，就可以像使用外部插件一样应用它了：
// my-implementation/build.gradle.kts
plugins {
id("org.my.gradle.plugin") version "internal" // "internal" 或你在resolutionStrategy中指定的版本
}
// ... 其他构建配置这里的version "internal"是一个占位符，实际版本将由根settings.gradle.kts中的resolutionStrategy根据gradle.properties中的版本进行解析。
注意事项
- Gradle版本兼容性：上述includeBuild与pluginManagement结合使用的方法在Gradle 7.5及更高版本中得到了良好的支持。对于旧版本，可能需要查阅相应版本的文档。
- 版本管理：通过resolutionStrategy集中管理内部插件的版本，可以确保整个多模块项目中的插件版本一致性，避免版本冲突。
- 构建顺序：includeBuild()的引入使得Gradle能够智能地识别并优先构建被包含的插件项目，从而使其输出（插件Jar）在主构建的其他模块解析依赖时可用。
- 理解复合构建：复合构建不仅仅用于插件，它还可以用于将多个独立的库项目组合到一个主构建中，实现跨项目依赖的本地开发和测试，而无需发布到本地Maven仓库。
总结
在多模块Gradle项目中构建和消费内部插件是一个常见的需求，通过巧妙地利用Gradle的复合构建特性，特别是includeBuild()指令和插件模块内部的settings.gradle.kts文件，可以有效地解决插件发现问题。这种方法不仅简化了开发工作流，还提高了项目内插件的集成效率和可维护性。遵循上述步骤，开发者可以在同一仓库内无缝地开发、构建和使用自定义的Gradle插件。
