根项目build.gradle仅作全局配置，不写构建逻辑；子项目build.gradle显式声明插件、依赖和任务；settings.gradle是子项目注册唯一入口，路径必须精确匹配。
根项目 build.gradle 只做全局配置，不写具体构建逻辑
根项目的 build.gradle 不该出现 java 插件、sourceSets 或 jar 任务配置。它的唯一职责是统一管理所有子项目的共性行为：插件版本锁定、仓库地址、依赖约束、公共 task 注册。一旦你在根项目里写了 apply plugin: 'java'，所有子项目都会被强制套上 Java 构建逻辑——哪怕其中一个是纯 Kotlin 脚本模块或 Gradle 插件项目，立刻报错。
常见错误现象：Could not find method java() for arguments [...] on root project，本质是误把子项目级 DSL 当成根项目可用语法。
- 只保留
plugins { id "com.gradle.enterprise" version "3.14.1" apply false }这类声明式插件（apply false是关键） - 用
subprojects { ... }或allprojects { ... }块统一设置repositories和ext共享变量 - 禁止在根项目中定义
dependencies块——依赖必须下沉到具体子项目
子项目 build.gradle 必须显式声明插件和构建目标
每个子项目（如 app/、core/）的 build.gradle 才是真正干活的地方。它要明确回答三个问题：我是谁（plugin）、我用什么（dependencies）、我要产出什么（tasks）。Android 模块得加 com.android.application，Java 库模块得加 java-library，Kotlin DSL 模块得加 org.jetbrains.kotlin.jvm——缺一不可。
容易踩的坑：直接复制根项目的 build.gradle 内容到子项目，结果导致插件重复应用、依赖冲突、classes 目录生成错乱。
- 必须以
plugins { id '...'开头，且不带apply false -
dependencies块只能出现在子项目中，用implementation project(':core')引用兄弟模块 - 如果子项目需要自定义打包行为（比如生成 fat jar），必须在自己的
build.gradle里重写shadowJar或bootJar任务
settings.gradle 是子项目注册的唯一入口
Gradle 不会自动扫描子目录。你看到的 app 和 core 模块能被识别，全靠 settings.gradle 里那行 include ':app', ':core'。漏掉任何一个，执行 ./gradlew projects 就看不到它，更别说编译了。
路径写错是高频问题：include ':app' 对应目录是 ./app，不是 ./modules/app；如果真要放深层路径，必须同步写 include ':modules:app' 并确保目录结构匹配。
-
rootProject.name = 'my-system'只影响根项目显示名，不影响构建逻辑 - 多级嵌套模块（如
services:user-service）必须用冒号分隔，不能用斜杠 - 不要在
settings.gradle里写逻辑判断或读取环境变量——它只负责静态声明
子项目之间依赖必须用 project() 形式，不能写坐标
子项目 A 想用子项目 B 的代码，必须写 implementation project(':core')，而不是 implementation 'com.example:core:1.0'。后者会让 Gradle 去远程仓库找，根本找不到本地模块，最终编译失败。
性能影响明显：用 project() 时，Gradle 能触发增量构建——改了 core 的源码，只重新编译 core 和依赖它的 app；如果误写成坐标形式，就退化成全量下载+编译，失去多项目优势。
- 跨层级引用（如
:services:auth→:shared:utils）路径必须完整，不能省略中间段 - 循环依赖会直接导致构建中断，Gradle 会报
Circular dependency between projects - 如果某个子项目只是提供脚本工具（比如 Gradle 插件），它不该被其他模块
implementation project(...)，而应通过buildSrc或includedBuild方式集成
settings.gradle 的刚性约束——它不是可选配置，而是构建拓扑的唯一事实来源。路径写错半字符，整个子项目就从构建图里消失。
