build.gradle：是什么、语法与Android配置

什么是 build.gradle？

build.gradle 是一个用 Groovy（.gradle 扩展名）或 Kotlin（.gradle.kts）语言编写的构建脚本，管理 Android 应用程序编译的所有方面。Gradle 是 Google 于 2013 年采用的标准 Android 自动构建系统。build.gradle 描述了：应用了哪些插件（Android、Kotlin、库），连接了哪些依赖项，使用了哪些 SDK 版本，如何签署应用程序以及在何处发布。

构建过程包括三个阶段：Initialization（确定模块）、Configuration（执行 build.gradle 脚本）、Execution（执行任务）。build.gradle 在 Configuration 阶段执行，此时 Gradle 创建任务图。在此阶段确定构建变体、计算依赖项和配置任务。重要提示：build.gradle 是代码，而不仅仅是配置。它可以使用条件语句、循环、方法调用和外部脚本。

Gradle 文件存储在模块根目录（app/build.gradle）和项目根目录（build.gradle）中。此外，Gradle 支持 apply from — 连接外部 Gradle 脚本。这允许将重复的逻辑提取到具有公共设置的文件中。随着 Convention Plugins（AGP 7+）的出现，apply from 被视为已弃用 — Convention Plugins 提供了一种类型安全且可组合的方式来在模块之间重用配置。

build.gradle 的演变

自 2013 年以来，build.gradle 的语法经历了重大变化：从具有动态配置的 Groovy 到具有编译时检查的 Kotlin DSL。AGP 从 1.0 版本发展到 8.7（2025）。关键里程碑：AGP 3.0（Java 8 desugar、new variant API），AGP 4.0（view binding、Java 11），AGP 7.0（默认 Kotlin DSL、Java 11 min），AGP 8.0（non-transitive R classes、Kotlin 中的构建配置），AGP 8.7（KSP 替代 kapt、快速配置）。

Project-level 和 Module-level build.gradle

Project-level build.gradle（根目录）为所有模块指定公共的插件、仓库和配置。主要块：plugins（连接 Gradle 插件）、repositories（依赖源：mavenCentral、google、jitpack）。根 build.gradle 中通常没有 android 块 — 它出现在模块中。Project-level 还可以包含 subprojects 块用于所有子项目的公共配置，尽管 Convention Plugins 更受青睐。

Module-level build.gradle（例如 app/build.gradle）描述特定模块。如果模块是应用程序，则应用 com.android.application 插件。如果是库，则应用 com.android.library。Module-level 包含：android 块（compileSdk、defaultConfig、buildTypes、productFlavors）、dependencies 块（模块的依赖项）以及用于配置测试和构建的可选块。Module-level 在 project-level 之后执行，可以覆盖公共设置。

从 AGP 8.0 开始，根 build.gradle 可以使用 version catalogs（libs.versions.toml）来集中管理依赖版本。Version catalog 是 gradle/ 目录中的一个文件，包含版本、库和插件。在 build.gradle 中，依赖项通过 libs 连接：implementation(libs.retrofit)。Version catalogs 对于新项目是必需的，并推荐用于所有具有三个或更多模块的项目。

// settings.gradle.kts — 项目根目录
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts（项目级别）
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts（模块级别）
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy 对比 Kotlin DSL

Groovy 是一种动态 JVM 语言，是 Gradle 的原始语法。Groovy 脚本（.gradle）使用动态类型：可以省略类型，可以使用或不使用引号，可以调用编译阶段不存在的方法。Groovy 的灵活性也是其缺点：IDE 无法在脚本执行前检查语法和类型，导致在参数名称或类型错误时出现运行时错误。

Kotlin DSL（.gradle.kts）使用 Kotlin 的静态类型。IDE 检查类型，通过自动完成建议可用参数，并在编辑阶段高亮显示错误。Kotlin DSL 在 Configuration 阶段较慢（由于将 .kts 文件编译为字节码），但 Google 不断改进性能：AGP 8.5+ 使用 Gradle Configuration Cache 和 Caching Kotlin DSL compilation，将差异减少到 1-2 秒。

Google 推荐所有新项目使用 Kotlin DSL 并逐步迁移现有项目。从 Groovy 迁移到 Kotlin DSL 很简单：引号替换为括号，添加类型，运算符转换为函数。大多数库在文档中提供 Kotlin DSL 示例。对于复杂情况（Custom Plugin、Task Graph），Kotlin DSL 提供类型安全 API，并防止在 Groovy 中只能在运行时发现的错误。Version catalogs（libs.versions.toml）对两种语法的工作方式相同。

android 块：应用程序配置

compileSdk、minSdk 和 targetSdk

android 块 — module-level build.gradle 的核心元素。在其内部配置：namespace（用于 R 和 BuildConfig）、compileSdk、defaultConfig、buildTypes、productFlavors、sourceSets、compileOptions、packaging、bundle。android 块的所有参数仅适用于 Android 模块。如果模块是库，则使用库插件代替应用程序，并且 android 块中没有 applicationId。

compileSdk — 编译代码所用的 SDK 版本。应等于最新的 Android API（编写本文时为 35）。minSdk — 支持的最低 API 版本。targetSdk — 应用程序目标版本（此版本的行为更改将适用）。compileSdk 和 targetSdk 之间的区别：compileSdk 确定可用的 API，targetSdk 确定运行时行为。建议：compileSdk = latest，targetSdk = latest - 1（用于测试对新更改的适配）。

compileOptions 设置 Java 兼容性：sourceCompatibility 和 targetCompatibility。AGP 8+ 需要 Java 17+ 进行编译。packaging 管理来自库的文件的包含：exclude、merge、pickFirst 用于解决 META-INF 冲突。buildFeatures 启用/禁用 ViewBinding、DataBinding、Compose。aaptOptions 配置资源处理：ignoreAssetsPattern、cruncherEnabled。android 块的每个元素优化构建的特定方面。

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

依赖管理

BOM（Bill of Materials）

依赖项在 build.gradle 中是连接到项目的库和模块。dependencies 块与 android 块位于同一级别。Gradle 支持多种配置：implementation（库在此模块中可用，非传递性）、api（库对依赖模块传递性可用）、compileOnly（仅用于编译，不包含在 APK 中）、runtimeOnly（仅运行时）、annotationProcessor / ksp（注解处理器）、testImplementation（仅用于测试）、androidTestImplementation（仅用于仪器测试）。

从 AGP 8.0 开始，Non-Transitive R classes — 每个库都有自己的 R 类，防止资源冲突。在 dependencies 块中，使用正确的配置很重要：implementation 不暴露传递性依赖，从而加快构建速度。api 暴露 — 当库从另一个库导出类型时使用（例如，Retrofit 在其公共 API 中使用 OkHttp 类型）。

对于版本管理，建议使用 BOM（Bill of Materials）— 一个确定库的兼容版本的构建文件。Firebase BOM：implementation(platform("com.google.firebase:firebase-bom:33.0.0"))。连接 BOM 后，只需指定库名称而不指定版本 — BOM 将自动选择兼容版本。这消除了不同库的传递性依赖之间的冲突。BOM 适用于 Firebase、Compose、Kotlin、Ktor、AndroidX。

dependencies {
    // BOM — 版本管理
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX 和 Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase（BOM 版本）
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // 测试
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

多模块项目中的 build.gradle

在多模块项目中，每个模块都有自己的 build.gradle。将一个模块连接到另一个模块使用 implementation(project(":module-name")) 语法。Gradle 在模块配置更改时自动构建它。多模块架构改善了构建时间（增量构建、并行性）并在功能模块、核心模块和库之间分配责任。

多模块项目的关键问题 — 配置重复。如果 10 个模块具有相同的 minSdk、compileSdk 和 Compose 依赖项，那就是不同 build.gradle 中的 10 份副本。解决方案 — Convention Plugins（以前是 buildSrc）。Convention Plugin 是一个用 Kotlin 编写的 Gradle 插件，应用于模块：plugins { id("myapp.android.library") }。该插件包含公共配置，更改会立即应用于所有模块。

为了组织 Convention Plugins，使用项目根目录中的 build-logic/ 目录。它包含 settings.gradle 中的 includeBuild 和 Kotlin 插件。Convention Plugins 可以发布到 maven 仓库以便在项目之间重用。Google 推荐 Convention Plugins 作为多模块项目的标准，替代 subprojects { } 和 apply from。切换到 Convention Plugins 将模块的 build.gradle 减少到 10-15 行。

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — 使用 Convention Plugin 后
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}