Android 深度实践

Appearance

Android 构建系统概览 ​

源：Android 官方文档 - 配置 build

Android 构建系统基于 Gradle 和 Android Gradle 插件（AGP），用于将源代码编译、打包成 APK 或 AAB，以便在 Android 设备上测试、部署和分发应用。本章节深入讲解 Android 构建系统的核心概念、配置方式和最佳实践。

核心术语 ​

Build Types ​

构建类型定义 Gradle 在构建和打包应用时使用的特定属性，通常针对开发生命周期的不同阶段进行配置。

  • Debug 构建类型：启用调试选项，使用调试密钥签名，未启用代码压缩和混淆
  • Release 构建类型：启用代码压缩、混淆处理，使用发布密钥签名以进行分发

每个 Android 项目必须至少定义一个构建类型。详见 Build Types 配置。

Product Flavors ​

产品变种用于创建应用的不同版本，每个版本可以有不同的功能和资源配置。

常见使用场景：

  • 免费版 vs 付费版
  • Demo 版 vs 完整版
  • 不同的服务器环境（开发、测试、生产）

详见 Product Flavors 配置。

Build Variants ​

构建变体是构建类型和产品变种的组合。AGP 会为每种组合自动创建构建变体。

命名规则：<flavor><BuildType>

kotlin
// 如果有 demo 和 full 两个 flavor
// 以及 debug 和 release 两个 build type
// AGP 将自动创建以下 4 个变体：
// - demoDebug
// - demoRelease
// - fullDebug
// - fullRelease

Android Build 中的 Java 版本 ​

无论源代码使用 Java、Kotlin 或两者混合，都需要在多个位置为构建选择 JDK 或 Java 语言版本：

  1. Gradle 运行时 JDK：运行 Gradle 本身的 JDK 版本
  2. 编译源代码的 JDK：编译 Java/Kotlin 代码时使用的 JDK
  3. 源码兼容性：源代码使用的 Java 语言特性版本
  4. 目标兼容性：生成的字节码兼容的 Java 版本

详细配置参见官方文档 Android build 中的 Java 版本。

构建配置文件 ​

Android 项目的构建配置通过多个文件定义，这些文件使用 Kotlin DSL 或 Groovy DSL 进行编写。

Gradle Wrapper 文件 ​

gradle/wrapper/gradle-wrapper.properties 定义了项目使用的 Gradle 版本：

properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

Gradle Settings 文件 ​

settings.gradle.kts 或 settings.gradle 定义项目级别的配置，包括：

  • 项目名称
  • 包含的模块（子项目）
  • 插件管理配置
  • 依赖解析仓库
kotlin
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "MyApplication"
include(":app")
include(":feature:login")
groovy
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = 'MyApplication'
include ':app'
include ':feature:login'

顶层 Build 文件 ​

build.gradle.kts 或 build.gradle（项目根目录）通常用于配置应用于所有模块的通用配置：

kotlin
plugins {
    id("com.android.application") version "8.7.3" apply false
    id("com.android.library") version "8.7.3" apply false
    id("org.jetbrains.kotlin.android") version "2.1.0" apply false
}

tasks.register<Delete>("clean") {
    delete(rootProject.layout.buildDirectory)
}
groovy
plugins {
    id 'com.android.application' version '8.7.3' apply false
    id 'com.android.library' version '8.7.3' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.0' apply false
}

tasks.register('clean', Delete) {
    delete rootProject.layout.buildDirectory
}

模块级 Build 文件 ​

每个模块的 build.gradle.kts 或 build.gradle 定义特定于该模块的构建配置：

kotlin
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

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"
            )
        }
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}
groovy
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    namespace 'com.example.app'
    
    compileSdk 36
    
    defaultConfig {
        applicationId 'com.example.app'
        minSdk 24
        targetSdk 36
        versionCode 1
        versionName '1.0'
    }
    
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = '17'
    }
}

dependencies {
    implementation 'androidx.core:core-ktx:1.15.0'
    implementation 'androidx.appcompat:appcompat:1.7.0'
}

Gradle Properties 文件 ​

gradle.properties 用于配置 Gradle 构建属性，包括：

  • JVM 内存配置
  • Gradle Daemon 配置
  • 构建缓存配置
  • Android 专项配置
properties
# Gradle JVM 配置
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8

# 启用 Gradle 配置缓存
org.gradle.configuration-cache=true

# 启用并行构建
org.gradle.parallel=true

# 启用构建缓存
org.gradle.caching=true

# Android 专项配置
android.useAndroidX=true
android.enableJetifier=false
android.nonTransitiveRClass=true

源代码集 ​

源代码集（Source Sets）定义了 Gradle 应从何处获取源文件。Android 项目通常包含多个源代码集：

  • main：所有构建变体共享的代码和资源
  • debug：仅用于 debug 构建类型的代码和资源
  • release：仅用于 release 构建类型的代码和资源
  • {flavorName}：特定产品变种的代码和资源
  • {flavorName}{BuildType}：特定构建变体的代码和资源

默认源代码集目录结构：

src/
├── main/
│   ├── java/
│   ├── kotlin/
│   ├── res/
│   └── AndroidManifest.xml
├── debug/
│   ├── java/
│   └── res/
├── release/
│   ├── java/
│   └── res/
├── demo/
│   └── res/
└── demoDebug/
    └── java/

详见 源代码集管理。

版本目录 ​

版本目录（Version Catalog）是管理依赖项版本的推荐方式，通过 gradle/libs.versions.toml 文件集中管理所有依赖项版本。

toml
[versions]
agp = "8.7.3"
kotlin = "2.1.0"
coreKtx = "1.15.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" }

详细配置参见 Version Catalog 配置。

DSL 配置基础 ​

Android Gradle 插件提供的 DSL 是声明式的，旨在让你指定"构建什么"而非"如何构建"。

Kotlin DSL vs Groovy ​

Android 官方强烈推荐使用 Kotlin DSL，主要优势包括：

  • 更好的 IDE 支持（代码补全、类型检查）
  • 编译时类型安全
  • 更好的重构支持
  • 与 Kotlin 语言生态统一
kotlin
android {
    namespace = "com.example.app"
    compileSdk = 36
    
    defaultConfig {
        applicationId = "com.example.app"
        minSdk = 24
        targetSdk = 36
    }
    
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
        }
    }
}
groovy
android {
    namespace 'com.example.app'
    compileSdk 36
    
    defaultConfig {
        applicationId 'com.example.app'
        minSdk 24
        targetSdk 36
    }
    
    buildTypes {
        release {
            minifyEnabled true
        }
    }
}

关键差异：

  • Kotlin DSL 使用 = 赋值，Groovy 直接使用空格
  • Kotlin DSL 属性名使用驼峰式（如 isMinifyEnabled），Groovy 省略 is 前缀
  • Kotlin DSL 字符串使用双引号，Groovy 可以使用单引号或双引号

与项目同步 ​

当修改构建配置文件后，需要点击 Android Studio 工具栏的 "Sync Now" 或使用 "File > Sync Project with Gradle Files" 来同步项目。同步过程会：

  1. 解析构建脚本
  2. 下载缺失的依赖项
  3. 配置 Android Studio 的项目结构
  4. 生成必要的构建文件