settings.gradle必须放在根目录且用相对路径include子项目，路径需与文件夹名完全一致；子项目复用配置需用subprojects或allprojects块；跨项目依赖路径须与settings中include严格匹配；复合构建适用于跨仓库场景。
多项目结构怎么组织才不踩 settings.gradle 的坑
Gradle 多项目构建失败，八成出在 settings.gradle 写错位置或漏掉 include。它不是可选配置，而是 Gradle 找到子项目的唯一入口，必须放在根目录，且所有子项目路径必须用相对路径、不能带 .gradle 后缀。
-
include 'api'正确；include 'api/'或include 'api.gradle'都会报Project directory 'xxx/api/' does not exist - 子项目名必须和实际文件夹名完全一致（大小写敏感），比如文件夹叫
web-service，就不能写成include 'WebService' - 如果子项目嵌套两层（如
services/auth），要写成include 'services:auth'，冒号是 Gradle 的路径分隔符，不是斜杠
子项目如何复用根项目的 build.gradle 配置
根项目的 build.gradle 默认只作用于自身，子项目不会自动继承。想统一管理依赖版本或插件，得用 subprojects 或 allprojects 块，但二者行为不同：
-
allprojects包含根项目 + 所有子项目，适合设通用仓库、启用公共插件（如java-library） -
subprojects只对子项目生效，更适合统一配置 JDK 版本、测试框架或发布逻辑 - 避免在
subprojects里写apply plugin: 'application'—— 不是所有子项目都要打包成可执行 Jar，容易导致Could not find method mainClassName()
示例：统一 Java 版本
subprojects {
apply plugin: 'java'
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
跨项目依赖为什么总报 Could not resolve project ':xxx'
这个错误不是路径写错了，就是子项目没被正确识别。Gradle 要求依赖声明中的项目路径必须和 settings.gradle 中的 include 完全匹配，且只能在子项目的 build.gradle 里用 project(':xxx') 引用其他子项目。
立即学习“Java免费学习笔记（深入）”；
- 依赖写在根项目的
build.gradle里？无效。根项目不能直接依赖子项目（除非显式配置evaluationDependsOn，但不推荐） - 子项目 A 依赖 B，但 B 没出现在
settings.gradle中？Gradle 根本不知道 B 存在，报错是必然的 - 用了
implementation project(':common-utils')，但settings.gradle里写的是include 'utils'？路径不一致，必报错 - IDE 显示依赖正常但命令行构建失败？检查是否启用了
--no-daemon或缓存污染，先运行./gradlew --stop && ./gradlew clean
什么时候该用 composite build 而不是普通多项目
普通多项目要求所有代码都在同一代码仓库、同一 Git 工作区。一旦某个模块是独立维护的第三方库（比如你公司内部的 SDK），或者你想临时替换一个远程依赖为本地源码调试，就得用 includeBuild 做复合构建。
- 在根项目的
settings.gradle里加includeBuild '../sdk-core'，就能让当前工程“假装”那个外部目录是自己的子项目 - 复合构建下，
project(':sdk-core')依赖依然有效，但它的build.gradle会被完整执行，不受当前工程的subprojects影响 - 注意：复合构建不能嵌套（即被 include 的项目不能再
includeBuild其他项目），否则会循环解析失败 - CI 环境中慎用 ——
includeBuild的路径是相对的，Jenkins 或 GitHub Actions 很可能找不到目标目录
多项目真正的复杂点不在语法，而在于模块边界是否清晰。一个 common 模块被十个子项目依赖，结果它悄悄引入了 Spring Boot，整个构建就会因类路径冲突而不可控。拆分前先想清楚：这个模块到底提供什么契约？谁消费？谁维护？
