复合构建是gradle中跨仓库复用独立项目的机制，通过includebuild实现依赖替换，要求被包含项目有合法settings.gradle、模块名匹配且提供正确变体。
复合构建（Composite Build）是 Gradle 提供的一种机制，让你能在不发布到仓库的前提下，把多个独立可运行的项目“临时组合”进当前构建中，特别适合同时开发一个应用和它所依赖的 SDK、公共库或插件。关键不是让它们变成子项目，而是保持各自独立性的同时实现依赖替换和实时联动。
明确复合构建和多项目构建的区别
别混淆这两个概念：多项目构建（multi-project build）要求所有模块在同一个代码仓库里，通过 settings.gradle 的 include 声明，共享根构建配置；而复合构建适用于跨目录、跨仓库甚至不同团队维护的项目——每个被引入的项目都自带 settings.gradle 和完整构建逻辑，Gradle 把它当作一个“黑盒构建”来执行，并用其产出替换当前项目中声明的对应依赖。
- 多项目：结构固定，如
app→lib-core→lib-utils，路径写死，共用一个gradle.properties - 复合构建：结构松散，如你的
my-app依赖公司内部的auth-sdk（存放在另一个 Git 仓库），你只需把它拉到本地某路径，然后告诉 Gradle：“这个 jar 包，别去 Maven 下载，直接用它本地构建出来的结果”
用 includeBuild 声明包含构建
在主项目的 settings.gradle.kts（或 settings.gradle）中添加 includeBuild，指向目标项目的根目录：
includeBuild("../auth-sdk") {
dependencySubstitution {
substitute module("com.example:auth-sdk") using project(":auth-sdk")
}
}
注意三点：
- 路径必须是相对路径，且目标目录下必须存在有效的
settings.gradle（哪怕内容只有rootProject.name = "auth-sdk"） -
substitute module(...)中的 group:name 要和你在主项目build.gradle中写的implementation "com.example:auth-sdk:1.0"完全一致 - 如果被包含项目使用 Kotlin DSL，确保它的
build.gradle.kts正确声明了插件和仓库，否则 Gradle 无法解析其依赖
被包含项目需满足基本条件
不是随便一个文件夹都能被 includeBuild，它本身得是一个合法的 Gradle 构建：
- 必须有
settings.gradle或settings.gradle.kts，且能成功识别 root project - 不能自己也是复合构建（即不能嵌套
includeBuild） - 推荐在它的
build.gradle中显式声明publishing插件或至少输出apiElements/runtimeElements变体，否则依赖替换可能失败 - 如果它用 Kotlin 编写，注意
kotlin-gradle-plugin版本要与主项目兼容，否则会出现 “unresolved reference” 或编译器不匹配
验证是否生效
运行 ./gradlew dependencies --configuration compileClasspath，查看依赖树里对应模块是否显示为 project > ... 而非 jar > ...；或者直接修改被包含项目的源码，再执行主项目的 compileJava，看是否自动编译新代码——如果没触发，说明替换未生效，常见原因是 module 名不匹配或被包含项目未正确构建出可用变体。
不复杂但容易忽略
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
