该用include时是将本地项目作为子模块纳入同一构建，共享生命周期和配置；必须用includeBuild时是两个独立项目通过坐标匹配实现源码级依赖替换，保持构建隔离性。
什么时候该用 include，而不是 includeBuild
当你想把另一个本地项目“变成自己构建的一部分”，也就是让它和当前项目共享同一个 settings.gradle、同一个构建生命周期、同一个 Gradle Daemon 实例，就选 include。典型场景是：你正在拆分一个单体项目，把模块逐步独立成子项目，但还没到物理分离的程度；或者你维护的是一个统一仓库里的多模块 Android 项目（比如 :app、:network、:common），所有模块都在同一 Git 仓库下。
这时候你改 common 的代码，运行 ./gradlew assembleDebug，app 会自动编译并使用最新的 common 字节码——因为它们根本就是同一个构建里的两个 Project 实例。
-
include要求被引入项目必须是子目录（或通过相对路径可定位），且不能有自己独立的settings.gradle - IDEA 同步后，被 include 的模块会出现在 Project 视图里，作为普通 module 显示
- 依赖写法是
implementation project(':common')，不是坐标形式 - 如果被引入项目本身也用了
includeBuild或含pluginManagement块，容易触发冲突或同步失败
什么时候必须用 includeBuild
当你手头有两个完全独立的 Gradle 项目（不同 Git 仓库、不同根目录、各自有完整的 settings.gradle 和 build.gradle），又不想 publish 到本地 Maven，只想让主项目在编译时“临时替换”某个远端坐标为本地源码，就只能用 includeBuild。
比如你正在开发一个 SDK（my-sdk），同时在业务 App（my-app）里验证它。SDK 已经定义了发布坐标 com.example:my-sdk:2.1.0，App 的 build.gradle 里写的是 implementation 'com.example:my-sdk:2.1.0'。这时你在 my-app/settings.gradle 里加一行 includeBuild '../my-sdk'，Gradle 就会在解析依赖时，自动用 my-sdk 的源码构建结果替代远程仓库里同坐标的 jar/aar。
- 被
includeBuild的项目必须有合法的settings.gradle，且不能是另一个复合构建（即不能自己也调了includeBuild） - 坐标（
group、name、version）必须严格匹配，否则 Gradle 不会替换，仍走远端仓库 - IDEA 同步后，
my-sdk不会显示为 module，只在 External Libraries 下以 “Composite Build” 标识出现 - 执行
./gradlew dependencies可看到该依赖标记为composite build
includeBuild 常见失效原因
最常遇到的不是配不对，而是“配对了但没生效”。根本原因是 Gradle 的依赖解析顺序和坐标匹配机制比表面看起来更严格。
- 被引入项目的
build.gradle没正确声明group和version（例如只在publishing块里写了，但没在project.group和project.version设值） - 主项目依赖写的是
implementation project(':xxx')，而includeBuild只响应坐标依赖，两者不兼容 - 远端仓库（如 Maven Central）恰好存在同名同版本构件，且仓库优先级高于 composite build —— Gradle 默认不会覆盖，除非明确禁用远端仓库或用
resolutionStrategy强制 force - 路径含空格或中文，Windows 下尤其容易触发
Project directory not part of the build错误，建议全英文路径
一个容易被忽略的细节：构建隔离性
include 是强耦合：两个项目共用一套插件版本、JDK 配置、dependencyResolutionManagement 块。改一个地方，可能影响所有子项目。
includeBuild 是弱耦合：每个构建保持自己的插件、Java 版本、仓库配置。但代价是：如果 my-sdk 用了 Java 17，而 my-app 还在 Java 11，构建会失败——Gradle 不会帮你降级编译器，它只负责把构建结果“连起来”。
所以真正要选哪个，关键不在“怎么配”，而在“你愿不愿意让这两个项目共享构建上下文”。如果答案是否定的，哪怕多配几行，也该用 includeBuild。
