gradle复合构建不是合并项目而是保持独立复用产出，适用于跨仓库、未发布、需联调场景；仅当被联调项目为独立git仓库、含settings.gradle.kts且未发布到maven时才适用，同仓库应优先用多项目构建。
Gradle 的 Composite Builds（复合构建）不是把多个项目“合并成一个”，而是让它们保持各自独立，同时在当前构建中实时复用彼此的产出——特别适合跨仓库、未发布、需联调的场景。
确认是否真需要复合构建
先判断：被联调的项目是不是独立 Git 仓库？它有没有自己的 settings.gradle.kts（哪怕内容为空）？它是否尚未发布到 Maven/Nexus，但你又想边改边调试？满足这三点，才适合用复合构建。同仓库项目请直接用 include 多项目结构，更轻量、IDE 支持更好。
三步完成基础接入
以主项目 my-app 联调独立 SDK 项目 auth-sdk 为例：
- 确保
auth-sdk根目录下存在settings.gradle.kts（Gradle 识别独立构建的硬性要求） - 在
my-app/settings.gradle.kts中添加：includeBuild("../auth-sdk")（路径是相对于当前settings.gradle.kts的） - 在
my-app/build.gradle.kts中，仍按原方式声明依赖，比如：implementation("com.example:auth-sdk:1.0.0")—— Gradle 会自动用auth-sdk构建出的 jar 替换这个坐标
处理模块名冲突与依赖替换
如果被包含项目发布的坐标和主项目里写的不一致（比如 auth-sdk 实际发布的是 com.example:core-auth），就要显式配置替换：
- 在
my-app/settings.gradle.kts的includeBuild块内加dependencySubstitution - 例如：
includeBuild("../auth-sdk") {<br> dependencySubstitution {<br> substitute module("com.example:core-auth") with project(":auth-core")<br> }<br>} - 这样写之后，所有对
com.example:core-auth的引用都会被替换成auth-sdk里的:auth-core模块
调试与常见问题
复合构建后，IDE（IntelliJ）默认支持源码跳转和断点调试，但需注意：
- 修改
auth-sdk源码后，需手动触发./gradlew build或等 IDE 自动构建其子任务，否则my-app不会感知变更 - 若提示 “Cannot resolve symbol” 或依赖未生效，优先检查：
–auth-sdk是否有合法settings.gradle.kts
–my-app的依赖坐标是否与auth-sdk的publishing配置完全匹配
– 是否误把多项目结构的include和复合构建混用
