Gradle include和includeBuild应该怎么选-java教程-PHP中文网

该用include时是将本地项目作为子模块纳入同一构建，共享生命周期和配置；必须用includeBuild时是两个独立项目通过坐标匹配实现源码级依赖替换，保持构建隔离性。

gradle 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 的依赖解析顺序和坐标匹配机制比表面看起来更严格。

Gradle 9.8.0

下载

被引入项目的 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 错误，建议全英文路径