AGP 构建脚本概览与核心参数分类

1.1 什么是 AGP 及其核心作用

Android Gradle Plugin（AGP）是 Android 官方构建系统的支柱。它本质上是 Gradle 的一个强大插件，负责将您的源代码、资源、依赖项和清单文件转换为可安装的 APK 或 App Bundle（AAB）。

AGP 的核心作用可以概括为：

• 变体管理：自动组合构建类型与产品变种，生成不同的构建版本。
• 配置管理：统一管理编译 SDK、最低 SDK、目标 SDK、版本号等核心参数。
• 任务编排：组织超过百个 Gradle Task（如编译、打包、签名、混淆），构建完整流程。
• 性能调优入口：几乎所有构建性能优化（如增量编译、资源缩减）都通过 AGP 参数暴露。

1.2 核心参数分类体系

AGP 构建脚本中的参数可以归纳为三大类：构建类型、产品变种和默认配置。这三者在构建变体生命周期中相互交织，形成最终的构建产物。

1.3 默认参数的常见影响

下面几个参数直接影响构建产物质量和开发效率：

1.4 构建变体生命周期

变体的生成遵循一个固定的组合流程。AGP 会将 buildTypes 和 productFlavors 做笛卡尔积，生成所有可能的 构建变体。

下面的 SVG 清晰地展示了这一流程：

1.5 关键配置示例

以下是一个典型的模块级 build.gradle 配置骨架，展示了核心参数的声明位置：

android {
    namespace "com.example.myapp"
    compileSdk 34

    defaultConfig {
        applicationId "com.example.myapp"
        minSdk 24
        targetSdk 34
        versionCode 1
        versionName "1.0.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            signingConfig signingConfigs.release
        }
        debug {
            minifyEnabled false
            applicationIdSuffix ".debug"
        }
    }

    productFlavors {
        demo {
            applicationIdSuffix ".demo"
            versionNameSuffix "-demo"
        }
        full {
            applicationIdSuffix ".full"
        }
    }
}

1.6 常见错误与修复

• 错误：compileSdk 低于 targetSdk
  现象：编译时直接报错，提示 compileSdk 必须 >= targetSdk。
  修复：确保 compileSdk 始终设置为与 targetSdk 相同或更高的版本。
• 错误：产品变种未设置唯一 applicationId
  现象：安装多个变体时发生冲突，提示“应用未安装”或签名冲突。
  修复：为不同变种添加 applicationIdSuffix，确保安装包在设备上具有唯一标识。
• 错误：随意修改 buildToolsVersion
  现象：强制锁定过旧的版本，导致某些 AGP 特性不可用或出现兼容性警告。
  修复：通常将此字段注释掉，让 AGP 自动选择合适的版本。