Gradle报“Project directory not part of the build”最常见原因是settings.gradle中include路径与磁盘目录名不严格一致：大小写、连字符、层级冒号分隔符（非斜杠）、无空格/中文，且对应目录下必须存在build.gradle文件。
settings.gradle 里 include 的路径必须和磁盘目录严格一致
Gradle 报 “Project directory not part of the build” 或 “Project with path 'xxx' could not be found”，最常见原因是 settings.gradle 中的 include 路径和实际子项目文件夹名不匹配。比如磁盘上是 opencv-4.6.0，但你写了 include ':opencv460'；或者目录在 libs/opencv460，却漏写了前缀 include ':libs:opencv460'。
注意大小写和连字符：macOS/Linux 区分大小写，Windows 虽不敏感但 IDE（如 Android Studio）内部解析仍按大小写匹配；my-lib 和 mylib 是两个不同路径。
-
include中的冒号是层级分隔符，不是文件系统路径分隔符，include ':common:utils'对应的是common/utils子目录 - 路径中不能含空格或中文，否则 Gradle 初始化阶段会直接失败，且错误信息不明确
- Android Studio 同步时若路径错，可能连
Gradle工具窗口都不出现——因为根本没识别成合法构建
子项目目录存在，但 Gradle 就是找不到
确认目录真实存在后，还要检查它是否被 .gitignore 或 idea/misc.xml 隐藏，或被 IDEA 错误标记为“excluded”。右键点击该目录 → Mark Directory as → 确保不是 Excluded；同时检查 .idea/modules.xml 是否残留了旧模块引用，干扰新 include 解析。
更隐蔽的问题是：子项目根目录下缺少 build.gradle（哪怕内容为空）。Gradle 多项目构建要求每个 include 的路径下必须有 build.gradle 文件，否则视为无效 project。
- 如果子项目是纯 Java 模块，至少要有空的
build.gradle，内容可仅为plugins { id 'java' } - Android 模块还必须有
src/main/AndroidManifest.xml（即使只是占位），否则 AS 可能拒绝加载 - 执行
./gradlew projects命令，能列出所有已识别的 project；如果目标模块不在其中，说明include没生效或路径错
用了 includeBuild 却提示目录不存在
includeBuild 和 include 完全不是一回事：includeBuild('../other-project') 要求括号内是另一个完整 Gradle 构建的根目录，即该路径下必须有 settings.gradle（或 settings.gradle.kts）和至少一个 build.gradle。它不接受相对路径拼写错误，也不接受软链接未展开的路径。
常见陷阱：
- 路径用的是相对路径，但当前工作目录不是
settings.gradle所在目录（比如你在子模块里执行命令） - 目标目录有
settings.gradle，但里面没include任何 module，导致整个构建为空，Gradle 认为“没项目可引入” - 使用了 Kotlin DSL 的
settings.gradle.kts，但语法错误导致解析失败，静默跳过，表现为“目录存在但不生效”
IDEA / Android Studio 同步后仍看不到子项目
同步失败往往不是 Gradle 的问题，而是 IDE 缓存或视图配置问题。先看 Event Log：如果有 “Failed to load project structure” 或 “Cannot resolve symbol ‘xxx’”，优先检查 settings.gradle 语法和路径；如果日志干净但项目树里没出现，试试以下操作：
- 关闭项目 → 删除
.idea目录 → 重新用 Open（不是 Import）打开根目录 - 确保 Project 视图（Alt+1）处于激活状态，而不是 Packages 视图（后者只显示源码包结构，会隐藏非 Java 文件和根级目录）
- 检查
File > Project Structure > Modules，确认子项目是否被列为独立模块而非嵌套在父项目下——这说明include生效了，但可能被误设为 “Import as Maven project”
真正容易被忽略的是：Gradle 的 include 只影响构建时的 project 依赖图，不影响 IDEA 的文件索引范围。如果子项目目录被 IDE 自动标记为 “Excluded”，即便 include 正确，你也看不到它的源码高亮和跳转。这个细节一旦漏查，可能反复重试半天 settings 文件而毫无进展。
