settings.gradle中include声明模块路径需显式指定，格式为include ':module-name'，冒号表示根项目子目录；模块名须与目录名一致或通过projectDir手动映射，且对应目录下必须存在build.gradle或build.gradle.kts文件。
settings.gradle 里用 include 声明目录路径
Gradle 不会自动扫描子目录，必须显式告诉它“这个目录是个模块”。关键动作就一行：include ':module-name'，写在根项目的 settings.gradle 或 settings.gradle.kts 里。模块名里的冒号是约定，表示它是根项目的直接子项目；名称通常取自目录名，但不强制一致——只要后续 project(":xxx") 引用时能对上就行。
常见错误现象：Could not find method include() for arguments [:xxx]，说明你误写到了 build.gradle 里，include 只能在 settings.gradle 中使用。
- 如果目录名含连字符（如
my-api），模块名建议用引号包裹：include ':my-api' - 模块名不能以数字开头，也不能含空格或特殊符号（除连字符、下划线外）
- 执行
./gradlew projects后看不到新模块？先确认该目录下存在build.gradle或build.gradle.kts
子模块不在当前目录下，怎么指定 projectDir
默认情况下，Gradle 认为 include ':xxx' 对应的目录就是根目录下的 xxx/。如果模块实际在别处（比如上级目录、同级其他文件夹、甚至绝对路径），就得手动修正它的物理位置。
在 settings.gradle.kts 中写法是：project(":xxx").projectDir = file("../other-repo/xxx")；在 settings.gradle（Groovy）中则是：project(':xxx').projectDir = new File('../other-repo/xxx')。
- 路径支持相对（相对于
settings.gradle所在位置）和绝对两种方式 - 务必在
include之后再设置projectDir，顺序反了会报Unknown project ':xxx' - Windows 下用反斜杠容易出错，统一用正斜杠或
File.separator
自动注册多个子模块：避免手写 include
当子模块数量超过 5 个，挨个写 include 容易漏、难维护。可以用脚本自动发现并注册——前提是每个子模块目录下有 build.gradle 或 build.gradle.kts。
Kotlin 版（settings.gradle.kts）：
fun autoRegisterModule(dir: File = settingsDir, ignoreSubDirs: Array<String> = emptyArray()) {
val ignoreDirs = arrayOf(".gradle", ".idea", ".git", "build") + ignoreSubDirs
dir.listFiles()?.forEach { f ->
if (!f.isDirectory || ignoreDirs.contains(f.name)) return@forEach
if (f.listFiles()?.any { it.name in listOf("build.gradle", "build.gradle.kts") } == true) {
include(":${f.name}")
println("注册模块: ${f.name}")
}
}
}
autoRegisterModule()
Groovy 版（settings.gradle）：
def autoRegisterModule() {
def ignoreDirs = [".gradle", ".idea", ".git", "build"]
settingsDir.eachDir { dir ->
if (ignoreDirs.contains(dir.name)) return
if (dir.listFiles()?.any { it.name in ["build.gradle", "build.gradle.kts"] }) {
include ":${dir.name}"
println "注册模块: ${dir.name}"
}
}
}
autoRegisterModule()
- 脚本不会递归进子目录，只扫一级；想支持嵌套需额外逻辑
- 如果某个目录下只有
src/没有构建文件，它不会被识别为模块 - 脚本运行后，仍需确保各模块的
build.gradle正确声明了插件（如java-library）
为什么 include 之后还编译失败？检查 build.gradle 是否就绪
include 只让 Gradle “看见”模块，不保证它能构建。真正决定能否编译的是子模块自己的 build.gradle 文件内容。
最容易被忽略的点：新目录里只有源码、没有 build.gradle，或者只有空文件、或者用了旧版插件（如 apply plugin: 'java' 但没配 Java 版本）。此时 Gradle 会静默跳过该模块，或者在执行 ./gradlew build 时报 Plugin [id: 'java'] was not found 这类错误。
- 最简可用的
build.gradle至少要包含：plugins { id 'java' } - Android 模块还需在
settings.gradle中启用插件：enableFeaturePreview('VERSION_CATALOGS')（视 AGP 版本而定） - 如果子模块依赖其他模块，记得在它的
build.gradle里写implementation project(':other-module')，而不是用 Maven 坐标
