20、Android项目构建：Android Gradle插件、构建变体（Build Variants）、签名配置

说到Android项目构建，我估计不少同学第一反应就是「点那个绿色三角跑一下就行」。嗯，确实能跑，但真要你配置多渠道打包、区分测试环境和生产环境、管理签名文件，很多人就开始挠头了。

这一章，咱们就把Android构建的三大核心掰开揉碎讲清楚：Android Gradle插件、构建变体、签名配置。搞懂这三样，你才算真正入了Android构建的门。

20.1 Android Gradle 插件——构建的发动机

Android Gradle插件，说白了就是Gradle世界里专门为Android项目定制的「翻译官」。它把Gradle的通用构建能力，翻译成Android能懂的打包、混淆、签名、资源处理等操作。

在项目的根build.gradle里，你会看到类似这样的声明：

// 项目级 build.gradle
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.2.0"
    }
}

然后在模块级的build.gradle里应用插件：

// 如果是应用模块
plugins {
    id 'com.android.application'
}

// 如果是库模块
plugins {
    id 'com.android.library'
}

Android Gradle插件到底干了什么？我简单列几个关键任务：

• 合并资源：把多个模块的资源文件合并到一起，处理冲突
• 编译源码：把Java/Kotlin编译成class文件，再转成dex
• 处理Manifest：合并多个模块的AndroidManifest.xml
• 签名对齐：调用zipalign优化APK，再用签名工具签名
• 构建变体：根据配置生成不同版本的APK

嗯，这里要注意：插件版本不同，API可能会有差异。比如AGP 7.0之后强制要求使用plugins块，不再推荐apply plugin写法。如果你还在用老项目，迁移时记得踩一脚刹车。

20.2 构建变体——一套代码，多端输出

构建变体（Build Variants）是Android构建中最灵活、也最容易让人晕的概念。它由两个维度组合而成：

维度	说明	常见例子
构建类型 (buildTypes)	定义构建的调试/发布属性	debug、release
产品风味 (productFlavors)	定义产品的不同版本	free、paid、china、global

两个维度组合起来，就是构建变体。比如freeDebug、freeRelease、paidDebug、paidRelease。每个变体都可以有自己的代码、资源、依赖和配置。

来看一个实际配置：

android {
    defaultConfig {
        applicationId "com.example.app"
        minSdk 21
        targetSdk 34
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        debug {
            // debug包可以调试，不混淆
            debuggable true
            minifyEnabled false
            // 加个后缀，方便区分
            applicationIdSuffix ".debug"
        }
        release {
            debuggable false
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }

    productFlavors {
        free {
            applicationIdSuffix ".free"
            versionName "1.0-free"
        }
        paid {
            applicationIdSuffix ".paid"
            versionName "1.0-paid"
        }
    }
}

你可能会问：如果某个变体我不想生成怎么办？用variantFilter：

android {
    variantFilter { variant ->
        def names = variant.flavors*.name
        // 如果风味是free且构建类型是release，跳过
        if (names.contains("free") && variant.buildType.name == "release") {
            setIgnore(true)
        }
    }
}

我曾经在一个海外项目中，需要同时维护国内版和Google Play版。两个版本用的推送SDK不同，支付渠道也不同。用productFlavors分成了china和global两个风味，每个风味各自依赖对应的SDK，构建时自动选择。省去了手动切换分支的麻烦，也避免了合并冲突。

20.3 签名配置——给APK上身份证

Android应用必须签名才能安装到设备上。debug签名是Android SDK自动生成的，但release签名必须你自己配。

签名配置在signingConfigs块里定义：

android {
    signingConfigs {
        release {
            storeFile file("my-release-key.jks")
            storePassword "password123"
            keyAlias "my-alias"
            keyPassword "password456"
        }
        debug {
            // debug签名通常用默认的，但也可以自定义
            storeFile file("debug.keystore")
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

推荐的做法是这样的：

// gradle.properties（不提交到版本控制）
RELEASE_STORE_FILE=/path/to/keystore.jks
RELEASE_STORE_PASSWORD=your_store_password
RELEASE_KEY_ALIAS=your_key_alias
RELEASE_KEY_PASSWORD=your_key_password

// build.gradle 中引用
signingConfigs {
    release {
        storeFile file(RELEASE_STORE_FILE)
        storePassword RELEASE_STORE_PASSWORD
        keyAlias RELEASE_KEY_ALIAS
        keyPassword RELEASE_KEY_PASSWORD
    }
}

或者更安全一点，在CI/CD环境里通过System.getenv()读取环境变量：

signingConfigs {
    release {
        storeFile file(System.getenv("KEYSTORE_PATH") ?: "debug.keystore")
        storePassword System.getenv("KEYSTORE_PASSWORD") ?: ""
        keyAlias System.getenv("KEY_ALIAS") ?: ""
        keyPassword System.getenv("KEY_PASSWORD") ?: ""
    }
}

说到签名，还有一个容易踩的坑：签名对齐。Android要求APK在签名前必须用zipalign工具对齐，否则安装时会报错。AGP默认会在release构建中自动做对齐，但如果你自己写脚本打包，别忘了加这一步。

20.4 三者如何配合工作

把Android Gradle插件、构建变体和签名配置串起来，整个流程是这样的：

1. AGP读取build.gradle配置，解析出所有构建变体
2. 每个变体根据buildTypes和productFlavors确定自己的属性
3. 如果是release类型，应用对应的signingConfig签名
4. AGP执行编译、打包、对齐、签名，输出APK

举个例子，你执行./gradlew assemblePaidRelease，AGP会：

• 找到paid风味的配置和release构建类型的配置
• 合并src/paid/和src/release/的代码资源
• 用release签名配置给APK签名
• 输出app-paid-release.apk

我个人习惯在项目初期就把构建变体搭好，哪怕当前只有一个风味。因为后续加渠道、加环境配置是迟早的事。提前搭好框架，后面就是往里填配置，省心很多。

好了，这一章的内容就到这里。构建变体和签名配置是Android构建的基石，搞懂了它们，你就能灵活控制APK的产出方式。下一章咱们聊聊依赖管理和版本控制，那也是日常开发中绕不开的话题。

---