settings.gradle（或.kts）是Gradle构建的总开关，必须显式include所有模块（如include ':app'），路径用冒号分隔；需分离配置pluginManagement和dependencyResolutionManagement，否则插件或依赖无法解析。
settings.gradle（或 settings.gradle.kts）必须显式声明所有参与构建的模块，否则 Gradle 根本“看不见”它们——哪怕目录存在、build.gradle 写得再完整也没用。
include 语句怎么写才不报错
模块路径必须用冒号 : 分隔，不能用斜杠 / 或反斜杠 \；路径是逻辑路径，和物理目录结构可以不一致（但默认一致）。
-
include ':app'→ 对应根目录下的app/文件夹 -
include ':feature:login'→ 对应feature/login/目录（注意不是feature:login文件夹） -
include ':core:data', ':core:network'→ 一次性 include 多个，用逗号分隔 - 如果模块在非标准位置（比如平级的
../shared-lib），得配合project(':shared').projectDir = file('../shared-lib')
常见错误：把 include 'app'（漏掉冒号）或 include './app'（用了点路径）当合法写法，结果同步失败，日志里只报“Project with path ‘:app’ could not be found”。
pluginManagement 和 dependencyResolutionManagement 必须分开配
Gradle 7.0+ 强制要求插件仓库（pluginManagement）和普通依赖仓库（dependencyResolutionManagement）分离配置。混写或只配一个，会导致插件找不到（如 com.android.application）或依赖解析失败（如 androidx.core:core-ktx）。
-
pluginManagement只管插件本身从哪下载，必须包含mavenCentral()、gradlePluginPortal()等；Android Studio 自带的 AGP 插件也走这里 -
dependencyResolutionManagement管所有implementation、api类依赖，可额外加私有 Nexus、Maven Local、Google Maven 等 - 两个块都必须出现在
settings.gradle顶层，且不能嵌套在rootProject或其他作用域里
典型坑：只在 build.gradle 里写了 mavenCentral()，但 settings.gradle 没配 dependencyResolutionManagement，结果 CI 上跑不通——因为 Gradle 8.0+ 默认禁用项目级仓库（FAIL_ON_PROJECT_REPOS 错误）。
Version Catalog（libs.versions.toml）怎么接入 settings
要让 Version Catalog 生效，必须在 dependencyResolutionManagement 块里显式启用，并指向 TOML 文件路径。
- 先确保
gradle/libs.versions.toml存在且格式正确（键名全小写+下划线，如[versions.junit]） - 在
settings.gradle.kts中写：versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } - 注意路径是相对于
settings.gradle所在目录的；如果文件在根目录下，就用file("gradle/libs.versions.toml") - Groovy 版需用
versionCatalogs { create("libs") { from(file("gradle/libs.versions.toml")) } }
没配这一步，libs.versions.xxx 在任何 build.gradle 里都会报 unresolved reference，IDE 也不提示补全。
includeBuild 和动态条件 include 容易被忽略的细节
includeBuild 用于复合构建（比如本地调试一个还没发版的 SDK），而条件性 include 常用于环境隔离（如只在 CI 加入测试模块），这两者都依赖 settings.gradle 的执行时机。
-
includeBuild('../my-internal-sdk')路径必须是相对路径，且目标目录下必须有合法的settings.gradle；否则报 “No build found” - 条件 include 不要用
if (System.getenv("CI") == "true") { include ':ci-only' }—— Gradle 初始化阶段不保证环境变量稳定，推荐用providers.systemProperty("ci").getOrElse("false") == "true" -
includeBuild里的插件版本会覆盖主工程的pluginManagement配置，容易引发版本冲突，建议在pluginManagement里统一约束
最隐蔽的问题：includeBuild 后，IDE 可能无法识别子构建中的模块依赖，需要手动触发 “Reload project” 或清缓存；而条件 include 如果判断逻辑出错，会导致某些模块彻底消失在 Project 视图里，连编译错误都看不到。
