settings.gradle中include路径必须严格匹配磁盘相对路径，如include(":user-api")对应目录必须为user-api而非modules/user-api；冒号为命名空间分隔符，非路径分隔符，嵌套模块platforms:auth-core对应目录platforms/auth-core；kotlin dsl需写include(":common")，不可省略括号；路径禁用空格、中文及特殊字符。
settings.gradle 里 include 的路径必须和文件系统一致
Gradle 不会自动扫描子目录，include 声明的路径必须严格对应磁盘上的相对路径。比如你写了 include(":user-api")，但实际目录是 modules/user-api，那 Gradle 就找不到这个模块——它只认你写的字符串，不猜路径。
常见错误现象：Project directory ':user-api' is not defined in settings file。这时候别急着改 build.gradle，先去检查 settings.gradle(.kts) 里的 include 是否拼错、是否漏了前导冒号、是否多了一层 src 或 main。
- 路径中不能含空格或中文，否则 Windows 下容易出问题
- 嵌套模块如
platforms:auth-core，对应目录必须是platforms/auth-core，不是platforms/auth/core - 如果用 Kotlin DSL（
settings.gradle.kts），include是函数调用，括号不能省：include(":common")，不是include ":common"
根 build.gradle 和子模块 build.gradle 的职责要切开
根 build.gradle（或 build.gradle.kts）只做三件事：声明插件、配置仓库、统一依赖版本约束；子模块的 build.gradle 只管自己该用什么插件、依赖哪些其他模块或外部库。
典型误操作是把所有依赖都写在根项目里，结果子模块编译时报 package xxx does not exist——因为根项目的 dependencies 不会自动传递给子模块。
- 根项目用
subprojects或allprojects统一 apply 插件，但不要在其中写具体业务依赖 - 子模块用
implementation project(':common')声明对其他模块的依赖，而不是implementation 'com.example:common:1.0' - Spring Boot 项目尤其注意：
spring-boot-starter-parent应由根项目通过plugins { id("org.springframework.boot") version "3.3.0" ... }统一引入，子模块不再重复声明 parent
模块命名带冒号时，目录结构不能有歧义
Gradle 模块名中的冒号 : 是命名空间分隔符，不是路径分隔符。比如 include(":platforms:core-config")，它对应的物理路径是 platforms/core-config，不是 platforms/core/config。Gradle 不会把 : 当成文件夹层级来解析。
容易踩的坑是看到 :a:b:c 就下意识建三级目录，结果构建失败。实际上 :a:b:c 就是一个扁平模块名，目录只要两层：a/b-c 或 a/bc 都可以，只要 settings.gradle 里写的和磁盘上的一致就行。
- 模块名建议全小写 + 连字符，避免大小写混用导致 macOS/Linux 下构建正常、Windows 下失败
- 不要用
.或_开头的模块名，某些 Gradle 版本会静默忽略 - 如果模块名含特殊字符（如
@、+），几乎肯定会触发解析异常，绕开不用
非标准布局（如平级服务目录）需要显式指定 rootDir
当你的代码库是 user-service/、order-service/、shared-lib/ 这种平级结构，且没有统一根 settings.gradle 时，Gradle 默认找不到模块。你得让每个服务自己成为“根”，并在其 settings.gradle 中用 rootProject.name 显式设名，再通过 includeBuild 引入其他本地项目。
例如 user-service/settings.gradle 写：includeBuild("../shared-lib")，这样它才能识别并编译 shared-lib 模块。但这属于跨根构建，IDE 支持弱，CI 流水线也容易出错，除非团队明确接受这种组织方式，否则不推荐。
- 更稳妥的做法是加一层聚合根目录，把所有服务软链接进来，或者用
includeFlat（仅 Groovy DSL 支持）临时兼容 -
includeFlat不支持 Kotlin DSL，KTS 用户必须改用标准嵌套结构 - CI 脚本里如果用
./gradlew build，务必确认当前工作目录是包含settings.gradle的那个根目录，否则会构建失败
settings.gradle 修改后没同步刷新 IDE 缓存，或者改了目录结构但忘了删掉 .gradle 和 build 文件夹——这两处残留经常导致“明明改对了却还是报错”。
