多模块构建需共享同一settings.gradle文件，所有子模块在同目录下由根项目统一声明；复合构建则通过includeBuild跨目录引入独立Gradle项目，按坐标动态替换依赖。
多模块构建必须共享同一个 settings.gradle
多模块构建（multi-project build）的本质是“单仓库、单构建上下文”。所有子模块都必须在同一个代码目录下，且由根目录的 settings.gradle 统一声明，比如 include ':app', ':lib-core', ':lib-utils'。Gradle 启动时先读这个文件，把它们全部注册为当前构建的一部分，后续编译、依赖解析、任务执行都在同一个构建生命周期里完成。
这意味着：模块间可直接用 project(':lib-core') 声明依赖；所有模块共用同一份 gradle.properties、pluginManagement 和 dependencyResolutionManagement 配置；IDE 同步后显示为一棵树状结构。
常见误操作包括：
– 把子模块挪到父项目外目录，却还在 settings.gradle 里写 include '../other-lib'（报错 Project directory not part of the build）
– 在子模块自己的 build.gradle 中重复定义 plugins 或 repositories，和根配置冲突
– 忘记在 settings.gradle 中显式设置 rootProject.name，导致 IDE 识别异常
复合构建引入的是完整独立构建，不是子模块
复合构建（composite build）的目标是“跨目录、跨仓库、不发布也能联调”。它不修改你当前项目的模块结构，而是通过 includeBuild '../auth-sdk' 或命令行 ./gradlew build --include-build ../auth-sdk，把另一个自带 settings.gradle 的 Gradle 项目当作黑盒构建来执行，并用它的产出（如 org.example:auth-sdk:1.0）替换当前项目中同坐标（group/artifact/version）的远程依赖。
关键点在于：
– 被引入项目必须能独立构建成功（./gradlew help 不报错）
– 它的 publishing 或 java-library 插件需启用，确保生成可用的组件元数据
– 当前项目 build.gradle 中仍写远程坐标依赖（如 implementation 'org.example:auth-sdk:1.0'），不是 project(...)
– 复合构建后，你能直接运行被引入项目的任务，比如 ./gradlew :auth-sdk:assemble
典型失败场景：
– 被引入项目用了 includeBuild 自身（复合构建不能嵌套）
– 坐标不匹配：你的依赖声明是 com.my:utils:2.1，但被引入项目 publishing.publications 输出的是 com.my:utils:2.0，替换失败
– 路径含空格或中文，Windows 下 includeBuild 解析失败（建议全英文路径）
依赖传递和版本控制逻辑完全不同
多模块构建中，依赖是静态解析的：A → B → C，B 模块的 api 依赖会透传给 A，C 的版本由 B 的 build.gradle 锁死，整个链路受 dependencyLocking 或 versionCatalogs 统一约束。
复合构建中，依赖是“按坐标动态替换”的：当前项目声明了 org.example:logging:1.5，只要某个 includeBuild 项目发布了同 group/artifact 的 1.5 版本构件，就自动使用其本地构建结果；其他版本（如 1.4 或 1.6）不会被干扰。
这意味着：
– 你无法靠复合构建解决“一个库多个版本冲突”问题（那是 resolutionStrategy 的事）
– 如果被引入项目本身依赖了 guava:32.0.0-jre，而你的主项目强制 guava:31.1-jre，最终行为取决于 dependencyResolutionManagement { versionCatalogs } 的合并策略，不是复合构建能控制的
– CI 环境默认不支持 includeBuild（路径不存在），必须改用发布快照版 + 私有仓库
什么时候该选哪个？看协作边界是否清晰
如果你和团队维护的是同一个 Git 仓库里的不同功能模块（比如 payment-service 和 user-service），它们长期共演进、共测试、共发版——用多模块构建。它结构紧、同步快、调试直，适合强耦合场景。
如果你只是临时调试一个外部 SDK（比如公司统一的 push-sdk），或者想在应用中验证一个尚未发布的插件（my-gradle-plugin），又或者两个项目由不同团队维护、CI 流水线完全隔离——用复合构建。它保持各自构建完整性，避免相互污染，是跨团队协作的事实标准。
最容易被忽略的一点：includeBuild 是构建时机制，不影响运行时类路径；它只改变“编译期用哪个 class 文件”，不改变 Class.forName 或反射行为。如果运行时报 NoClassDefFoundError，问题大概率出在被引入项目的 jar 打包遗漏了依赖，而不是复合构建本身没生效。
