gradle多模块项目只允许根目录存在一个settings.gradle（或.kts），子模块下多余的该文件会导致ide将其识别为独立项目而脱离父工程管理。
子模块目录下存在多余的 settings.gradle
这是最常见也最容易被忽略的根因。Gradle 多模块项目只允许一个 settings.gradle（或 settings.gradle.kts），且必须位于根目录。如果新添加的子模块目录里自带了一个 settings.gradle，IntelliJ IDEA 和 Gradle 会把它当作独立项目加载，导致它既不参与父项目的依赖解析，也不继承 ext 属性、pluginManagement 或仓库配置。
实操建议：
- 检查新子模块目录下是否意外生成了
settings.gradle—— 尤其是用 IDE “New Module” 向导创建时，某些旧版模板会自动写入 - 直接删除该文件，**不要保留**；所有模块声明必须统一收口到根目录的
settings.gradle中 - 确认根目录
settings.gradle里已包含对应include 'xxx'，路径名需与实际目录名严格一致（区分大小写，不带斜杠）
include 路径写错或未刷新 Gradle 项目
include 不是“扫描目录”，而是显式声明工程路径。写错路径、多写了 /、用了相对路径（如 ./submodule）或路径含空格但没加引号，都会让 Gradle 在初始化阶段跳过该模块。
实操建议：
- 在根目录
settings.gradle中，使用纯名称形式：include 'api', 'common', 'config'，不要写成include 'modules/api'（除非子模块真在modules/api下） - 修改完
settings.gradle后，必须手动触发 Gradle Refresh：右键项目 → Reload project，或点击 Gradle 工具窗口右上角的Refresh按钮 - 如果
Refresh按钮灰显，说明 IDEA 当前没识别出这是一个 Gradle 项目 —— 此时应先检查根目录是否存在build.gradle和settings.gradle
子模块缺少 build.gradle 或语法错误
即使 settings.gradle 正确 include 了，子模块若没有 build.gradle，或其中存在语法错误（比如 Groovy DSL 里用了 Kotlin 风格的 lambda、KTS 文件里用了 apply plugin:），Gradle 在配置阶段就会跳过该模块，IDE 也就不会将其注册为可构建单元。
实操建议：
- 确保子模块根目录下存在
build.gradle（Groovy）或build.gradle.kts（Kotlin DSL），且文件可被正常解析（无红色波浪线） - 临时删掉子模块
build.gradle中所有内容，只留最简结构验证：plugins { id("java") }（KTS）或plugins { id 'java' }（Groovy） - 避免在子模块
build.gradle中直接引用未定义的ext属性 —— 若依赖父项目属性，务必确认父项目build.gradle中已通过ext或versionCatalogs正确声明
IDE 缓存未清理导致模块状态残留
IDEA 对 Gradle 项目结构的识别有强缓存机制。新增模块后未刷新，或之前导入失败过，可能导致内部模块索引仍处于“未识别”状态，即使配置全对，UI 上仍显示为普通文件夹、右键无 Add as Gradle project。
实操建议：
- 执行 File → Invalidate Caches and Restart → Invalidate and Restart，这是最彻底的清理方式
- 重启后不要立即打开项目，先等 IDEA 完全启动完毕再通过 Open → 选择项目根目录 导入（而非 “Open recent”）
- 极少数情况下，手动删除项目根目录下的
.idea和所有*.iml文件，再重新导入（注意提前备份.idea/misc.xml中的编码/行尾设置）
settings.gradle 的存在性、路径正确性、以及是否被真正执行，这三个点漏掉任何一个，后续所有配置都白搭。
