前置条件检查：Gradle版本、JDK版本、Android SDK、插件依赖树
适用场景
本检查过程适用于所有计划升级 AGP（Android Gradle Plugin）版本的项目，包含以下典型场景：
- 从 AGP 4.x 升级至 AGP 7.x 或 8.x。
- 从 AGP 7.x 升级至 AGP 8.x 并迁移至新变体 API。
- 从 AGP 8.0 升级至 8.1/8.2 等小版本迭代。
- 在持续集成（CI）环境中自动化升级前的预检。
前置条件
| 检查项 |
前置条件说明 |
| 可访问项目源码 |
拥有完整项目仓库访问权限，可正常执行 ./gradlew 命令。 |
| 构建环境网络通畅 |
Gradle Wrapper 可访问 Gradle 官方仓库、Maven Central 或企业镜像。 |
| 本地 IDE 配置 |
Android Studio 已安装并打开项目，或命令行环境已配置 JAVA_HOME。 |
| 权限与凭证 |
具备读取本地缓存的权限，无写入代理冲突。 |
操作步骤
- 确认 Gradle 版本：检查
gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl。
- 确认 JDK 版本：运行
java -version 以及 ./gradlew -version 输出的 JVM 信息。
- 确认 Android SDK 版本：检查
local.properties 中 sdk.dir 路径，并确认已安装的目标 compileSdk 和 buildTools。
- 生成并校核插件依赖树：执行
./gradlew :app:dependencies --configuration runtimeClasspath > deps-tree.txt。
- 整合检查清单：将上述信息填入检查表格，核对 AGP 目标版本的最低要求。
提示：建议在干净的构建缓存环境中执行首次检查，避免缓存污染导致版本信息失真。
输入输出物
| 类型 |
物名称 |
来源 |
| 输入 |
gradle-wrapper.properties |
项目根目录 gradle/wrapper/ |
| 输入 |
local.properties |
项目根目录 |
| 输入 |
项目 build.gradle / build.gradle.kts |
各模块目录 |
| 输出 |
checklist-v2.html（版本检查报告） |
自动生成，含 Gradle / JDK / SDK / 依赖树四要素 |
| 输出 |
deps-tree.txt（依赖树文本） |
./gradlew :app:dependencies --configuration runtimeClasspath 重定向输出 |
责任边界
- 构建工程师：主导执行检查流程，填写检查表，发起版本变更评审。
- 开发组长：审批版本变更，确认兼容性报告。
- QA：依据检查报告验证 CI 环境一致性。
- 基础设施管理员：确保 SDK 在线下载权限、代理配置正确。
记录材料
| 记录名称 |
格式 |
保存位置 |
| 前置条件检查表 |
Markdown / Confluence 页面 |
项目文件 docs/upgrade/ 或 Wiki |
| 执行日志 |
文本 console.log |
CI 构建产物归档 |
| 版本快照记录 |
YAML 或 JSON |
gradle/versions/ 目录 |
异常处理
| 异常情形 |
处理措施 |
| Gradle Wrapper 不存在 |
重新生成 Wrapper：gradle wrapper --gradle-version 8.2 |
| JDK 版本低于目标要求（如 AGP 8.x 需 JDK 17） |
安装 JDK 17+ 并更新 JAVA_HOME；CI 镜像切换对应基础镜像。 |
| Android SDK 缺少 compileSdk/buildTools |
通过 sdkmanager 安装：sdkmanager "platforms;android-34" "build-tools;34.0.0" |
| 依赖树解析超时/网络错误 |
检查代理设置，使用 --offline 模式仅走本地缓存；或升级 Gradle 守护进程内存。 |
| 插件依赖树包含已废弃的变种（如 com.android.application 旧变体） |
记录废弃的依赖坐标，汇总至升级影响清单。 |
警告：若 JDK 版本低于 AGP 最低要求，未修正即执行升级构建，将直接导致 Unsupported class file major version 异常，且缓存状态可能被错误标记为“有效”，造成后续调试混乱。
验收标准
- 四维检查（Gradle 版本、JDK 版本、Android SDK、插件依赖树）全部满足 AGP 目标版本的最低要求。
- 生成的可读报告文件（checklist-v2.html）浏览器打开后，所有检查项显示为✅通过。
- 依赖树输出无红色（错误）或黄色（警告）节点。
- 检查过程产生的日志完整，时间戳连续，无中断性错误。
- 全体责任人在 2 个工作日内完成确认签字（或 CI 审批自动通过）。