2. 构建环境与版本信息采集

版本升级前，必须完整、准确地记录当前构建环境的所有关键组件版本号及扩展配置。遗漏任何一个版本信息，都可能因为依赖隐式兼容规则导致升级后缓存失效、编译中断或构建产物异常。本章给出各组件版本的标准化采集方法与验证步骤。

2.1 为什么版本信息如此重要

AGP 构建缓存由输入文件的哈希值决定命中与否。文件名、内容、编译器版本、JDK 版本、Kotlin 编译器版本、插件扩展配置中的每一处参数都被视为缓存键的一部分。以下是直接影响缓存兼容性的版本维度：

2.2 Gradle 版本采集

Gradle 版本由项目根目录下的 gradle/wrapper/gradle-wrapper.properties 文件中的 distributionUrl 指定。推荐同时记录 Gradle 运行时版本和 Wrapper 版本。

# gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

命令行确认运行时版本（需在项目根目录执行）：

./gradlew --version

输出示例：

------------------------------------------------------------
Gradle 8.4
------------------------------------------------------------

Build time:   2023-10-18 12:15:15 UTC
Revision:     c6b8e3b8f9cef8e5c7a9c0f2e3d4b5a6c7d8e9f0

Kotlin:       1.9.0
Groovy:       3.0.17
Ant:          Apache Ant(TM) version 1.10.13
JVM:          17.0.9 (Oracle Corporation 17.0.9+11)
OS:           Linux 5.15.0-86-generic amd64

记录目标：将 distributionUrl 字符串与 ./gradlew --version 输出的 Gradle 行一并保存至升级日志。

2.3 AGP 版本采集

AGP 版本来源于项目级 build.gradle 或 build.gradle.kts 中的 com.android.tools.build:gradle 依赖声明。采集时需同时记录顶级 build.gradle 中的 classpath 和各模块 apply plugin: 'com.android.application' 的使用情况。

// 顶层 build.gradle (Groovy DSL)
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:8.2.0"
    }
}

// 如果是 Kotlin DSL
// buildscript {
//     repositories {
//         google()
//         mavenCentral()
//     }
//     dependencies {
//         classpath("com.android.tools.build:gradle:8.2.0")
//     }
// }

命令行快速获取 AGP 版本：

./gradlew buildEnvironment | grep "com.android.tools.build:gradle"

输出示例：

\+--- com.android.tools.build:gradle:8.2.0

2.4 JDK 版本采集

AGP 8.0+ 要求 JDK 17 运行，但编译产出的字节码目标可由 compileOptions 指定。记录两个版本：

• 运行时 JDK：通过 java -version 或 ./gradlew --version 中 JVM 行获取
• 编译目标 JDK：从模块 build.gradle 的 compileOptions 块读取

# 运行时 JDK
java -version
# 输出示例
openjdk version "17.0.9" 2024-01-16 LTS
OpenJDK Runtime Environment (build 17.0.9+11-LTS)
OpenJDK 64-Bit Server VM (build 17.0.9+11-LTS, mixed mode)

// 模块 build.gradle 中 compileOptions
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

若使用 Gradle 工具链，还需记录 toolchain 配置。

2.5 Kotlin 版本采集

Kotlin 版本由 org.jetbrains.kotlin:kotlin-gradle-plugin 的 classpath 版本决定。采集方式：

# 顶层 build.gradle 中声明
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"

# 命令行查询
./gradlew buildEnvironment | grep "kotlin-gradle-plugin"

如果需要采集项目中 Kotlin 编译器具体版本（可能通过 kotlin 扩展覆盖）：

// 模块 build.gradle.kts
plugins {
    kotlin("android") version "1.9.22"
}

// 或者在 ext 中指定
ext.kotlin_version = "1.9.22"

2.6 Android Gradle 插件扩展配置采集

AGP 的 android { } 块中的 DSL 参数直接影响构建缓存键。以下是最关键的配置项，必须逐项记录：

推荐使用 Gradle 的 --info 日志模式导出所有解析后的 DSL 值：

./gradlew :app:properties --info | grep -E "android\.(compileSdk|minSdk|targetSdk|buildToolsVersion)"

更自动化：利用 Gradle Build Scan 或自定义 buildSrc 任务打印当前扩展配置。

2.7 版本信息采集流程综述

以下流程图汇总了从项目文件到最终版本清单的关键节点：

2.8 验证步骤

完成版本信息采集后，执行以下三步验证确保数据完整：

1. 交叉对比：将采集到的版本与 ./gradlew --version 输出进行比对，确认 Gradle、Kotlin、JVM 一致。
2. 依赖树检查：运行 ./gradlew :app:dependencies --configuration runtimeClasspath，确认 AGP 无隐式依赖冲突。
3. 缓存预验证：在 clean 状态下执行 ./gradlew :app:assembleDebug --build-cache --info 2>&1 | grep "Cache"，检查是否出现异常缓存错乱。

下一步（第三章）将基于本章采集到的版本清单，制定 AGP 版本升级策略与缓存兼容性评估矩阵。