在 Android Studio 的多模块项目中，Gradle 构建系统由多个配置文件协同工作，共同完成项目的编译、打包和依赖管理。理解这些文件的作用和相互关系，是高效开发和管理大型项目的关键。
1. settings.gradle - 项目结构总览
settings.gradle是整个项目的总指挥。它告诉 Gradle 哪些模块构成了这个项目，以及去哪里寻找构建所需的插件和依赖。
pluginManagement {
repositories {
maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
...
}
}
rootProject.name = "My Application"
include ':activity-bestpractices'
include ':popupwindow-bestpractices'
...include ‘:module-name’: 这是该文件最核心的功能，它告诉 Gradle 项目中包含哪些子模块。相当于 Maven 的<modules>。pluginManagement: 定义所有模块共享的插件仓库。Gradle 会在这里寻找并下载插件，类似 Maven 的<pluginRepositories>。dependencyResolutionManagement: 定义所有模块共享的依赖库仓库。这确保了整个项目都从同一个来源获取依赖，避免了版本冲突和不一致。类似 Maven 的<repositories>。rootProject.name：根项目名字。
2. libs.versions.toml - 依赖和插件版本中心
libs.versions.toml是 Gradle 的版本目录文件，它集中管理了项目中所有依赖和插件的版本号。类似 MavendependencyManagement的统一版本管理文件。
[versions]
agp = "8.10.1"
kotlin = "2.0.21"
coreKtx = "1.16.0"
...
[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
...
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
[versions]: 集中声明所有依赖和插件的版本号。[libraries]: 定义具体的依赖库，并引用[versions]中的版本号。例如：androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }[plugins]: 定义具体的插件，同样引用[versions]中的版本号。
使用版本目录的好处是，当你想更新某个依赖时，只需要修改这个文件中的版本号，就能确保所有使用该依赖的模块都同步更新，极大提高了项目的可维护性。
- 引用方式：
implementation(libs.androidx.core.ktx)
id(libs.plugins.android.application)3. 根目录build.gradle - 全局配置
根目录的build.gradle是项目的全局配置文件。它的主要职责是声明整个项目可能用到的插件，但不会立即应用它们。
plugins { … }: 在这个代码块中，你使用apply false来声明插件及其版本。例如：alias(libs.plugins.android.application) apply false。这表示这个项目“可以使用”这些插件，但具体的应用工作交给各个模块自己决定。
这种“声明与应用”的分离设计，使得根目录文件变得非常简洁，只专注于版本管理，而把具体的配置留给模块文件。
4. 模块build.gradle - 模块专属配置
每个模块都有自己的build.gradle文件，它是该模块的专属配置文件。它负责定义模块的具体行为和所需资源。
plugins { … }: 在这里，你真正地应用该模块所需的插件。例如，一个应用模块会应用id("com.android.application")，而一个库模块则会应用id("com.android.library")。android { … }: 在这个代码块中，你配置该模块特有的信息，例如包名、编译 SDK 版本、签名配置等。dependencies { … }: 这个代码块定义了该模块所依赖的所有库。这些依赖只对当前模块有效。
文件间的协同关系
这四个文件通过一种清晰的分工模式协同工作：
settings.gradle首先定义了项目的模块结构和依赖来源。libs.versions.toml提供了所有依赖和插件的统一版本信息。- 根目录
build.gradle声明了项目可以使用的插件及其版本，这些信息来自libs.versions.toml。 - 模块
build.gradle根据自身需求，从libs.versions.toml获取依赖，并从根目录的build.gradle中选择并应用所需的插件，最终完成模块的构建。
| 文件 | 作用 | 对子模块影响 |
| --- | --- | --- |
| settings.gradle | 定义模块、插件仓库、依赖仓库 | 所有模块都会使用这些仓库和 module 配置 |
| build.gradle (root) | 声明插件版本、全局配置、可选全局依赖 | 子模块可以引用插件版本（不用再写 version），也可以统一部分依赖或任务 |
| build.gradle (module) | 模块编译配置、插件应用、依赖声明 | 真正编译 APK / AAR，独立管理依赖，灵活性最高 |
这种层次分明、各司其职的结构，是 Gradle 在复杂多模块项目管理上的优势所在。
更新: 2025-09-03 23:18:27
原文: https://www.yuque.com/dongpozhouzi-mshe3/zhm85g/oh21acg6ewtg40e3