必须显式设置project(":xx").projectdir，否则include(":xx")无效；外部模块需自包含build.gradle、独立配置，且不可依赖父项目；ide需手动刷新识别。
project().projectDir 要显式设置，否则 include 无效
只写 include(":xx") 不会自动把外部目录拉进来——Gradle 默认只扫描当前 settingsDir 下的子目录。你必须手动指定该模块的实际位置，否则构建会报错 Project directory 'xx' does not exist。
在 settings.gradle.kts 中，先 include，再通过 project() 设置路径：
include(":xx")
project(":xx").projectDir = File(settingsDir, "../other-project")
注意两点：
-
File(settingsDir, "..")是相对路径，适用于团队协作（路径随项目移动） - 如果外部模块不在当前项目同级目录下，比如在
/home/user/libs/mylib，就得用绝对路径：project(":xx").projectDir = File("/home/user/libs/mylib") - 路径末尾不能带斜杠，
File("path/")和File("path")在某些系统上行为不一致
外部模块必须有独立的 build.gradle 或 build.gradle.kts
被引用的外部目录不是“文件夹”，而是一个合法的 Gradle 子项目：它必须包含自己的 build.gradle（或 build.gradle.kts），且不能依赖父项目的 build.gradle 配置（比如插件应用、仓库配置等）。
常见错误现象：
-
Could not compile script '.../build.gradle': Cannot access class 'org.gradle.api.plugins.JavaPlugin'→ 外部模块没声明plugins { id("java") } -
Could not resolve all files for configuration ':xx:compileClasspath'→ 外部模块没配repositories，或用了父项目里才定义的ext变量
建议做法：外部模块保持自包含，所有依赖声明、插件、仓库都写在自己的 build.gradle 里。
依赖声明仍用 project()，但 IDE 可能不自动识别
一旦外部模块被正确 include 并设置了 projectDir，你在主模块的 build.gradle 中照常写：
dependencies {
implementation project(":xx")
}
但 IntelliJ IDEA 或 Android Studio 有时不会立刻刷新这个链接，表现为：
- 代码跳转失败（Ctrl+Click 进不去外部模块源码）
- IDE 显示 “Unresolved reference” 但命令行
./gradlew build成功
解决方法：
- 执行
File → Reload project（或点击 Gradle 工具栏的刷新按钮） - 检查外部模块根目录下是否有
.idea或.gradle目录残留——有就删掉，避免缓存干扰 - 确认外部模块的
build.gradle中没有apply from: "../common.gradle"这类跨项目引用（会破坏独立性）
别和 includeBuild 混用，它们解决的是不同问题
include + project().projectDir 是把外部目录“挂进”当前构建，变成兄弟模块；而 includeBuild("../other-project") 是复合构建，外部项目保持完整生命周期，依赖靠坐标匹配（如 implementation "com.example:lib:1.0"）。
容易踩的坑：
- 在同一个
settings.gradle.kts里既写include(":xx")又写includeBuild("../other-project")，且两个路径指向同一目录 → Gradle 报错Duplicate project registration - 误以为
includeBuild后还能用project(":xx")声明依赖 → 不行，必须用 Maven 坐标 - 外部模块改了版本号但没同步更新
includeBuild的路径 → 构建时仍用旧缓存
真正需要“目录外子模块”的场景，基本就是想让两个物理分离的工程共享构建生命周期——这时 include + projectDir 是唯一正解，别绕弯。
