3. 根目录 settings.gradle 配置：include 与 projectDir、项目路径别名、模块集合管理

settings.gradle 是 Gradle 多模块项目的入口文件，它定义哪些模块参与构建、模块的逻辑名称与物理路径之间的映射关系，以及如何批量组织模块集合。本章围绕 include 声明、projectDir 重定向、路径别名（项目名称与目录解耦）以及集合管理展开，帮助你写出清晰、可复用、不易出错的配置。

3.1 include 声明：模块包含的基础

include 接收以冒号分隔的模块路径。每个路径对应一个逻辑项目名称，并默认将模块所在目录视为与逻辑名称相同的相对路径（相对于 settings.gradle 所在目录）。

// 最简单的 include 用法
include ':app'
include ':library'
include ':feature:search'

上述配置等价于：

3.2 projectDir 重定向：物理路径与逻辑名称解耦

当模块的源代码目录不在默认位置时（例如由于目录结构调整、外部模块存放位置不同），可以用 projectDir 属性将其指向真实的文件系统路径。

include ':core'
include ':legacy:analytics'

// 将 ':core' 指向 'libraries/core-engine' 目录
project(':core').projectDir = file('libraries/core-engine')

// 将 ':legacy:analytics' 指向外部目录
project(':legacy:analytics').projectDir = file('../shared/analytics-sdk')

重定向的典型场景：

• 仓库重组：模块从子目录迁移到独立的 libraries/ 目录，但希望保留现有逻辑名称。
• 外部依赖本地化：将第三方 SDK 源码放在项目外部，通过相对路径引入。
• 多项目共享模块：多个 Gradle 项目使用同一份模块源码，通过 projectDir 指向公共路径。

3.3 路径别名：使用不同的逻辑名称引用模块

通过 include 指定一个逻辑名称，再通过 projectDir 指向一个目录，可以实现“路径别名”——模块在构建脚本中的引用名称与其物理目录名称不同。

// 物理目录叫 'my-network-lib'
// 但在构建中希望用 ':networking' 引用
include ':networking'
project(':networking').projectDir = file('my-network-lib')

别名的作用：

• 命名统一：团队约定模块命名规范，不受目录名限制。
• 减少重构影响：当模块目录重命名时，只改 settings.gradle 中的 projectDir，不修改依赖它的所有 build.gradle。

3.4 模块集合管理：批量 include 与动态配置

当模块数量很大（例如 50+）时，逐行 include 会造成 settings.gradle 膨胀。以下技巧可以批量管理：

3.4.1 基于目录的自动 include

利用 Groovy 的 fileTree 或 eachDir 扫描指定目录下的子工程：

// 自动 include 'features/' 目录下的所有子目录
file('features').eachDir { dir ->
    include ":feature:${dir.name}"
    project(":feature:${dir.name}").projectDir = dir
}

// 或使用更灵活的闭包 + 排除
fileTree(rootDir) {
    include 'services/*/build.gradle'
    exclude 'services/legacy'
}.each { buildFile ->
    def dir = buildFile.parentFile
    def name = dir.name
    include ":service:${name}"
    project(":service:${name}").projectDir = dir
}

3.4.2 使用 gradle.properties 集中开关

将模块 include 与否改为属性开关，方便多 flavor 或多环境选择：

// gradle.properties
includeModuleA=true
includeModuleB=false

// settings.gradle
if (project.hasProperty('includeModuleA') && project.includeModuleA.toBoolean()) {
    include ':moduleA'
    project(':moduleA').projectDir = file('modules/moduleA')
}

// 读取列表
def enabledModules = (project.findProperty('enabledModules') ?: 'core,app').split(',')
enabledModules.each { name ->
    if (file("modules/$name").exists()) {
        include ":$name"
        project(":$name").projectDir = file("modules/$name")
    }
}

3.4.3 模块集合的声明式组织（推荐）

将模块列表提取到单独的文件或闭包中，保持 settings.gradle 整洁：

// settings.gradle
def moduleList = [
    [name: 'app',           path: 'app'],
    [name: 'lib-core',      path: 'libraries/core'],
    [name: 'lib-ui',        path: 'libraries/ui'],
    [name: 'feature-search',path: 'features/search'],
    [name: 'feature-login', path: 'features/login'],
]

moduleList.each { mod ->
    include ":${mod.name}"
    project(":${mod.name}").projectDir = file(mod.path)
}

3.5 内联结构图：settings.gradle 配置流程

3.6 常见错误与调试

• 路径不存在：projectDir 指向了不存在的目录，Gradle 会在配置阶段报错 "Project with path ':xxx' could not be found"。解决方法：检查相对路径基准，使用路径或 file(rootDir.resolve(...))。
• 模块重名：同时 include 了相同名称的模块（包括不同目录下同名），Gradle 会抛出 "Cannot add project with name 'xxx' as a project with that name already exists"。使用别名或嵌套命名空间区分。
• 循环 include：settings.gradle 中 include 了同一个模块两次（可能通过不同路径），会造成项目图冲突。每次构建仅需 include 一次。
• 动态 include 顺序影响：使用 eachDir 时如果目录遍历顺序不固定，可能导致 CI 和本地行为不一致。建议在 CI 中锁定 Gradle 版本并打印 includes 结果：在 settings.gradle 末尾添加 println "Included projects: ${rootProject.childProjects.keySet()}"。

3.7 性能与稳定性优化

通过合理地组合 include、projectDir 和模块集合管理，你可以让多模块项目的 settings.gradle 既简洁又灵活，为后续的动态交付、按需构建打下坚实基础。