复合构建是gradle将独立项目作为“黑盒构建”透明替换依赖二进制产物的机制；需被引入项目含settings.gradle(.kts)且能独立构建，主项目通过includebuild或--include-build声明，并依赖dependencysubstitution精确绑定模块。
Gradle 的 composite builds（复合构建）让你能在不修改项目源码或发布依赖的前提下，把多个独立的 Gradle 项目临时“组装”在一起编译、测试和运行。它特别适合跨模块协作开发、本地调试第三方库修改、或验证多仓库协同行为。
什么是 composite build？
复合构建不是把项目合并成一个，而是让 Gradle 在构建时“透明替换”某个依赖的二进制产物（如 jar/aar），改为其源码项目构建出的最新结果。比如项目 A 依赖 projectB:1.0，而你本地有 projectB 的源码，就可以让 A 直接使用 projectB 的源码构建结果，而非从 Maven 仓库下载 1.0 版本。
如何声明 composite build？
有两种常用方式：
-
命令行方式（临时）：在项目 A 根目录执行：
gradle --include-build ../projectB build
这样 projectB 会被作为 included build 加入当前构建生命周期。 -
配置文件方式（持久化）：在项目 A 的
settings.gradle(.kts)中添加：
// settings.gradle.ktsincludeBuild("../projectB")
或指定更精确路径：includeBuild("../libs/my-utils") { dependencySubstitution { substitute module("com.example:utils") with project(":") } }
关键前提与注意事项
要让 composite build 正常工作，需满足几个隐含条件：
- 被 include 的项目（如 projectB）必须是合法的 Gradle 项目（含
settings.gradle或settings.gradle.kts），且能独立构建成功。 - 项目 A 中原本通过
implementation 'com.example:projectB:1.0'声明的依赖，会被自动替换为 projectB 的publish产物（通常是java-library插件生成的 jar）。如果 projectB 没启用 publishing，Gradle 会 fallback 到其archives或defaultconfiguration，但建议显式配置publishing插件避免歧义。 - 若 projectB 有多个可发布的组件（如 api + runtime），可通过
dependencySubstitution精确绑定，例如：substitute module("com.example:projectB-api") with project(":api")
调试与排错技巧
复合构建有时不生效，常见原因和检查点：
- 执行
gradle dependencies --configuration compileClasspath查看依赖树，确认目标模块是否显示为project :而非com.example:projectB:1.0。 - 确保两个项目使用的 Gradle 版本兼容（尤其当 projectB 使用了新特性而项目 A 的 Gradle 太旧时）。
- 如果 projectB 用了 Kotlin DSL（
.kts），项目 A 的 Gradle 版本需 ≥ 5.0；Java DSL（.gradle）则兼容性更广。 - IDE（如 IntelliJ）可能不会自动识别 composite build 关系，需手动刷新项目或启用 “Delegate IDE build/run actions to Gradle” 选项。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
