Gradle的include语句注册的是逻辑项目路径而非物理目录名，必须用带冒号的路径如':billing'，再通过project(':billing').projectDir=file('payment-service')显式绑定实际目录，顺序不可颠倒。
子模块名称和目录名不一致时，include 写法必须用路径名，不是目录名
Gradle 的 include 语句注册的是“项目路径”，不是文件系统目录名。比如你有个子模块实际在 ./payment-service 目录下，但你想让它在构建中叫 :billing，就不能写 include 'payment-service'，而要写 include ':billing'，再手动绑定目录。
常见错误现象：IDEA 显示模块未识别、project(':billing') 找不到、同步时报 Project with path ':billing' could not be found。
-
include后面的字符串是 Gradle 内部使用的项目路径（逻辑名），必须带冒号前缀，且全局唯一 - 目录名只是磁盘上的文件夹名，Gradle 不自动推断它和项目路径的关系
- 如果目录名和项目路径不一致，必须显式调用
project(':billing').projectDir = file('payment-service')
settings.gradle 中如何绑定自定义项目路径到物理目录
绑定动作必须放在 include 之后，否则 Gradle 还没创建该项目对象，调用 project(...) 会报 Unknown project 错误。
以 Groovy 版本为例：
rootProject.name = 'myapp'
include ':billing'
include ':auth'
include ':shared'
project(':billing').projectDir = file('payment-service')
project(':auth').projectDir = file('identity-service')
project(':shared').projectDir = file('common-lib')
Kotlin DSL（settings.gradle.kts）写法稍有不同，要用 create 或直接赋值：
rootProject.name = "myapp"
include(":billing", ":auth", ":shared")
findProject(":billing")?.projectDir = file("payment-service")
findProject(":auth")?.projectDir = file("identity-service")
findProject(":shared")?.projectDir = file("common-lib")
- 不要在
include前操作project(...)，顺序错会导致 NPE 或配置丢失 -
file(...)是相对于settings.gradle所在目录的路径，不能写绝对路径（除非你明确加File(...)构造） - 改完后必须执行
./gradlew --stop && ./gradlew build或在 IDE 中 Reload project，缓存不清理会沿用旧映射
为什么改了 settings.gradle 还在 IDE 里看到旧模块名
IntelliJ IDEA 和 Android Studio 会把模块名（Module Name）和项目路径（project(':xxx')）两套名字分开缓存。即使 settings.gradle 已正确绑定，IDE 可能仍显示旧的 .iml 文件名或模块树结构。
典型表现：项目视图里显示 payment-service [payment-service] 或 billing [payment-service]。
- 先删掉
.idea/modules/下对应旧模块的.iml文件（如payment-service.iml） - 再删掉
.idea/misc.xml里残留的 - 最后点击 IDE 菜单
File → Reload project，让 IDEA 重新读取settings.gradle并生成新.iml - 如果仍不对，关掉项目、删掉整个
.idea/目录再重开（谨慎操作，会丢失本地 run configuration）
子模块名重复或含非法字符会直接失败
Gradle 对项目路径有严格校验：:billing:v2 合法，:billing-v2 合法，但 :billing v2（含空格）、:billing@v2（含 @）会报 Invalid project name；多个模块都叫 :model 也会在依赖解析阶段崩溃。
错误信息示例：Cannot add project ':model' as a dependency of project ':api': project ':model' already exists in the build.
- 项目路径中禁止空格、制表符、控制字符、
@#$%等 shell 或 Gradle 解析敏感符号 - 所有
include的路径必须全局唯一，哪怕它们在不同子目录下（如:lib:db:model和:app:feature:model仍算冲突） - 如果历史原因已存在同名模块，必须重命名其中一个，例如改为
:db-model和:feature-model，再同步更新所有implementation project(...)引用
真正容易被忽略的是：project(':xxx').projectDir 绑定只影响 Gradle 构建时的源码位置，不影响 IDE 的模块识别逻辑——后者还依赖 .iml 文件内容和 modules.xml 注册。两者不同步，就会出现“命令行能编译，IDE 报红”的割裂状态。
