复合构建适用于跨仓库、保持项目独立性的场景，通过includeBuild引入本地其他Gradle项目，并用坐标依赖（如implementation "com.example:auth-sdk:1.0.0"）声明，Gradle自动用其构建结果替换远程依赖。
不能直接“组合”两个独立项目——得先明确你要的是多项目构建（同一仓库）还是复合构建（跨仓库联动）。 两者底层机制、配置位置、依赖写法、调试行为完全不同，选错会导致 Sync 失败、断点不生效、资源找不到或构建卡死。
用 include 挂载子项目：适合合并到同一 Git 仓库的场景
这是把另一个项目当作当前项目的子模块拉进来，结构扁平化，共享同一个 settings.gradle 和根 build.gradle。调试时能跨模块跳转、断点穿透、实时看到修改效果。
- 把目标项目（比如
lib-core）整个目录复制进当前项目根目录下，例如：./modules/lib-core/ - 在根
settings.gradle中添加：include ":lib-core"（路径必须匹配实际目录层级） - 在主模块（如
:app）的build.gradle中改依赖为：implementation project(":lib-core") - 注意原
lib-core的build.gradle里如果有apply plugin: 'com.android.application'，要改成'com.android.library'，否则会报Cannot add task ':lib-core:assembleDebug' as a task with that name already exists - Android Studio 同步后，
lib-core会出现在 Project 视图的Android标签页下，可直接运行app并调试其中调用的lib-core代码
用 includeBuild 做复合构建：适合跨仓库、保持各自独立性的场景
你本地有项目 A（App）和项目 B（SDK），B 还在另一个 Git 仓库里维护，你不想把它挪进来，但又想在 A 里实时调试 B 的源码改动——这时候用 includeBuild。
- 确保项目 B 有合法的
settings.gradle（哪怕只有一行rootProject.name = "auth-sdk"），且能独立./gradlew build - 在项目 A 的
settings.gradle中添加：includeBuild "../auth-sdk"（路径是相对于 A 的根目录） - 在 A 的
build.gradle中，仍按坐标声明依赖，比如：implementation "com.example:auth-sdk:1.0.0" - Gradle 会自动拦截这个坐标请求，转而构建本地的
../auth-sdk，并将其输出（jar/aar）注入 A 的编译类路径 - 断点能打在 B 的源码上，但前提是 A 的 IDE 已正确识别 B 的源码路径；Android Studio 有时需要手动点击 “Refresh Gradle project” 或重启索引，否则会提示 “Source code does not match the bytecode”
常见失败现象和对应检查点
Sync 成功不代表调试可用。以下问题高频出现，且症状相似但根源不同：
-
Could not resolve project :lib-core→ 检查settings.gradle中include的路径是否拼错，是否漏了冒号，是否和文件系统实际嵌套层级一致 -
Configuration on demand is not supported→ 复合构建中，被includeBuild的项目若用了configure-on-demand = true，必须关掉（在它的gradle.properties中设为false） - 断点灰色、提示 “no executable code found” → 不是代码没编译，而是 IDE 没把 B 的源码路径映射进 A 的 classpath；尝试在 A 的
build.gradle中加android { sourceSets { debug.java.srcDirs += file("../auth-sdk/src/main/java") } }（仅临时绕过） - 资源引用报错，如
error: resource id not found→ 复合构建不传递资源，includeBuild只处理编译产物（jar/aar），带资源的 Android Library 必须用include方式挂载
真正麻烦的不是配置本身，而是混合使用两种方式：比如在 include 的多项目里又对某个子项目加 includeBuild，或者在复合构建中误删了被依赖项目的 build 目录导致缓存混乱。这类问题没有通用解法，只能看 --stacktrace 输出里第一个 Caused by 行定位到底哪一层构建崩了。
