本教程共 100 篇 · 第 21 篇 · 更新于 2026-07-28 · 约 9 分钟阅读

21. Gradle 构建系统

本节目标：理解 Gradle 在 Android 项目里干什么、看懂并会改 build.gradle.kts、会加依赖、会用 buildTypes 和 productFlavors 出多版本包、会配签名。

Gradle 是什么

Gradle 是个自动化构建工具，Android 用它把源码、资源、依赖打包成 APK。你点 Android Studio 的 Run，背后就是 Gradle 在干活：

下载依赖（AndroidX、Compose 等）。
编译 Kotlin/Java 源码成字节码。
编译资源（XML 转二进制）。
把字节码转成 dex。
打包成 APK。
签名（debug 自动签，release 要配）。

Android 通过 Android Gradle 插件（AGP） 给 Gradle 加 Android 特有的能力。

build.gradle.kts 的两种

一个项目至少有两个 build.gradle.kts：

顶层（项目级）：项目根目录，配置所有模块共享的东西。
模块级：每个模块（app、library）一个，配置具体模块。

顶层 build.gradle.kts

plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.compose.compiler) apply false
}

这里只声明插件，apply false 表示「先记下，模块里再应用」。新写法比老的 buildscript { classpath } 清晰。

模块级 build.gradle.kts

重点配置都在这。完整结构：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.compose.compiler)
}

android {
    namespace = "com.example.app"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.app"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }

    buildFeatures {
        compose = true
    }

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

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // ...
}

下面逐块拆。

defaultConfig：默认配置

defaultConfig {
    applicationId = "com.example.app"
    minSdk = 24
    targetSdk = 36
    versionCode = 1
    versionName = "1.0"
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
}

applicationId：应用唯一 ID，上架后不能改。
versionCode：整数版本号，每次更新递增。Google Play 用这个判断新旧。
versionName：显示给用户的版本字符串，如 "1.0.0"。
testInstrumentationRunner：仪器化测试用的 runner。

buildTypes：构建类型

控制 debug 和 release 两种构建的配置：

buildTypes {
    debug {
        applicationIdSuffix = ".debug"       // debug 包名加后缀，能跟 release 共存
        isDebuggable = true
        versionNameSuffix = "-debug"
    }
    release {
        isMinifyEnabled = true                // 开启混淆和压缩
        isShrinkResources = true              // 移除无用资源
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
        signingConfig = signingConfigs.getByName("release")   // 用 release 签名
    }
}

debug 类型默认存在，不用写也有。要自定义就显式声明。
release 开 isMinifyEnabled 后会用 R8 混淆代码、移除无用代码和资源，减小包体积、防逆向。
一个项目至少 debug 和 release 两个 BuildType，能加自定义（如 staging）。

productFlavors：产品风味

用同一套代码出多个版本的应用。常见场景：免费版/付费版、国内版/海外版、白标定制。

flavorDimensions += listOf("version", "channel")

productFlavors {
    create("free") {
        dimension = "version"
        applicationIdSuffix = ".free"
        versionNameSuffix = "-free"
    }
    create("paid") {
        dimension = "version"
        applicationIdSuffix = ".paid"
    }
    create("google") {
        dimension = "channel"
    }
    create("huawei") {
        dimension = "channel"
    }
}

每个维度（dimension）选一个 flavor 组合，最终生成 freeGoogle、freeHuawei、paidGoogle、paidHuawei 四种变体。Build Variants 面板里能切换。

每个 flavor 能有自己的源集（source set）：

src/
├── main/              所有变体共享
├── free/              free 变体独有
├── paid/              paid 变体独有
├── google/
└── huawei/

free/java/ 下的代码只在 free 变体编译时生效，可以放免费版特有的逻辑。

Note

flavorDimensions 必须声明维度，flavor 要属于某个维度。单维度时简单点：flavorDimensions += "version"。

签名配置

release 包要签名才能安装。配置 signingConfigs：

android {
    signingConfigs {
        create("release") {
            storeFile = file("keystore/release.jks")
            storePassword = "your_store_password"
            keyAlias = "your_key_alias"
            keyPassword = "your_key_password"
        }
    }

    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

Warning

别把密码硬编码提交到 Git。用 local.properties 或环境变量读取：

val props = rootProject.file("local.properties").let { 
    java.util.Properties().apply { if (it.exists()) load(it.inputStream()) }
}

signingConfigs {
    create("release") {
        storeFile = file(props.getProperty("RELEASE_STORE_FILE", ""))
        storePassword = props.getProperty("RELEASE_STORE_PASSWORD", "")
        keyAlias = props.getProperty("RELEASE_KEY_ALIAS", "")
        keyPassword = props.getProperty("RELEASE_KEY_PASSWORD", "")
    }
}

local.properties 不提交，密码留在本地。CI 上用环境变量。

依赖管理

dependencies {
    implementation(libs.androidx.core.ktx)                    // 编译和运行都包含
    implementation(platform(libs.androidx.compose.bom))       // BOM 统一版本
    implementation(libs.androidx.material3)
    api(libs.retrofit)                                        // 编译和运行包含，且暴露给依赖本模块的模块
    debugImplementation(libs.leakcanary.android)              // 只在 debug 包含
    testImplementation(libs.junit)                            // 单元测试用
    androidTestImplementation(libs.androidx.espresso.core)    // 仪器化测试用
    ksp(libs.hilt.compiler)                                   // KSP 注解处理器
}

依赖配置关键字：

关键字	作用范围
`implementation`	编译和运行，不暴露给上游模块（推荐）
`api`	编译和运行，且暴露给上游模块
`compileOnly`	只编译，不打包进 APK
`runtimeOnly`	只运行，不参与编译
`debugImplementation`	只在 debug 变体
`releaseImplementation`	只在 release 变体
`testImplementation`	单元测试
`androidTestImplementation`	仪器化测试
`ksp` / `kapt`	注解处理器（KSP 比 kapt 快）

Tip

优先用 implementation 而不是 api。api 会把依赖泄露给依赖你的模块，导致编译变慢、耦合增加。

BOM（Bill of Materials）

Compose 用 BOM 统一管理所有 Compose 库版本，不用每个单独写版本：

dependencies {
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.ui)              // 不用写版本
    implementation(libs.androidx.material3)       // 不用写版本
    implementation(libs.androidx.foundation)
}

BOM 保证 Compose 各库版本兼容，升版本只改 BOM 一处。

常用 Gradle 命令

命令行（项目根目录）或 Android Studio Terminal：

./gradlew assembleDebug        # 构建 debug APK
./gradlew assembleRelease      # 构建 release APK
./gradlew bundleRelease        # 构建 release AAB
./gradlew installDebug         # 构建 debug 并装到设备
./gradlew clean                # 清理构建产物
./gradlew lint                 # 运行 Lint 检查
./gradlew test                 # 跑单元测试
./gradlew dependencies         # 查看依赖树

Windows 用 gradlew.bat。Android Studio 的 Gradle 面板（右侧大象图标）能图形化执行这些任务。

同步与缓存

改了 build.gradle.kts 后要点 Sync Now（顶部黄条）让 Gradle 重新同步。不同步的话改的配置不生效。

构建慢的话：

开 Gradle 并行和缓存（gradle.properties）。
用 implementation 减少 api。
离线模式（断网时勾 Offline）。
升级 Gradle 和 AGP 版本。

小结

Gradle 把源码和资源打包成 APK。build.gradle.kts 分项目级和模块级。defaultConfig 设包名版本，buildTypes 区分 debug/release，productFlavors 出多版本，signingConfigs 配签名。依赖用 implementation 优先，Compose 用 BOM。改完记得 Sync。下一节深入 AndroidManifest。