📚 课程目录第2章开发环境搭建

2. 开发环境搭建：JDK与Gradle安装、Android Studio版本选择、环境变量配置错误排查

说实话，AGP 配置异常有一半以上都出在环境搭建阶段。我记得有个同事，JDK 版本装错，排查了整整两天——后来发现是项目用了 AGP 8.0，但 JDK 还是 11。这种坑，其实完全可以避免。下面我把自己这几年踩过的雷，给你捋一遍。

2.1 JDK 安装与版本选择

AGP 从 8.0 开始，推荐最低 JDK 17。我见过不少人还在用 JDK 8 / 11，结果 AGP 编译直接报 Unsupported class file major version。说白了，JDK 版本不对，后面全是白搭。

AGP 版本	最低 JDK	推荐 JDK
AGP 7.x	JDK 11	JDK 17
AGP 8.0 - 8.2	JDK 17	JDK 17 / 21
AGP 8.3+	JDK 17	JDK 21

个人习惯： 我一般直接装 JDK 21，向下兼容 JDK 17 的项目。省得以后换项目又要重装。

2.2 Gradle 安装与版本管理

Gradle 这玩意儿，版本和 AGP 有严格的对应关系。你想想看，如果 Gradle 8.0 配上 AGP 8.2，虽然能跑，但可能触发一些潜在 bug。我推荐你直接用项目自带的 Gradle Wrapper。这样团队统一版本，免去每个人本地装不同版本的烦恼。

但如果非要在本地装一个全局 Gradle，记得去官网 gradle.org/releases 下载。安装后跑 gradle -v 验证。

# 安装后检查版本
gradle -v

------------------------------------------------------------
Gradle 8.5
------------------------------------------------------------

Build time:   2023-12-11 12:00:00 UTC
Revision:     xxxxxx

Kotlin:       1.9.21
Groovy:       3.0.17
Ant:          Apache Ant(TM) version 1.10.13
JVM:          21.0.1 (Eclipse Adoptium 21.0.1+12)
OS:           Windows 11 10.0 amd64

  核心原则： 能用 Wrapper 就别装全局。我踩过最大的坑就是本地 Gradle 8.0，项目 Wrapper 是 8.2，结果 build 缓存莫名其妙失效。

2.3 Android Studio 版本选择

Android Studio 现在主要有三个 Channel：Stable（稳定版）、Beta（测试版）、Canary（金丝雀版）。我个人的建议是：

生产项目：永远用 Stable 最新版。别信什么新功能诱惑，我曾在 Canary 上遇到 AGP 预览版不兼容插件，回滚了两天。
学习 / 尝鲜：可以用 Canary，但记得备份项目。
注意 AGP 插件版本：Android Studio 自带的 AGP 版本不一定匹配你项目的版本，建议手动在项目级 build.gradle 里指定。

我曾经： 用 Android Studio 2023.1 (Hedgehog) 自带的 AGP 8.2 打开一个旧项目，项目里写的是 AGP 8.0，结果 sync 失败提示 Cannot resolve external dependency。其实只要在项目里显式声明 AGP 版本就行了。

2.4 环境变量配置

环境变量配不对，最常见的就是 JAVA_HOME 没设好。怎么判断？打开终端输入 echo %JAVA_HOME%（Windows）或 echo $JAVA_HOME（macOS/Linux）。如果输出空，或者指向了错误路径，那就需要修一下。

配置步骤建议：

安装 JDK 后，记下安装路径（例如 C:\Program Files\Java\jdk-21）。
设置 JAVA_HOME 环境变量指向该路径。
将 %JAVA_HOME%\bin 加入 PATH。
验证：打开新终端，执行 java -version 和 javac -version，看版本是否一致。

# Windows 命令行下检查 JAVA_HOME
echo %JAVA_HOME%
C:\Program Files\Java\jdk-21

# 检查 javac
javac -version
javac 21.0.1

避坑指南： 配完环境变量记得重启终端！我曾经在 macOS 上改了 .zshrc，忘了 source，然后疯了半小时。

2.5 常见环境搭建错误排查清单

这里我把这几年遇到的典型问题整理成一张表，直接拿来对照排查。

错误现象	可能原因	解决方向
`Unsupported class file major version 63`	JDK 版本过高，AGP 不兼容	降低 JDK 到 17 或 11（看 AGP 版本）
`Could not find com.android.tools.build:gradle:8.x`	AGP 版本写错或 gradle 仓库未配置	检查 `settings.gradle` 中的 `pluginManagement`
Android Studio sync 卡住不结束	Gradle 下载超时 / 代理问题 / 内存不足	检查 `gradle.properties` 中代理配置，或改用 Wrapper
`JAVA_HOME is not set` 或 `找不到 javac`	环境变量未正确配置	重新设置 JAVA_HOME 并加入 PATH，重启终端
AGP build 报 `Failed to notify build listener`	Gradle 缓存损坏或插件冲突	清理 `.gradle/caches` 并重新 sync

注意： 配好环境之后最好做一次「全链路验证」——创建一个空 Android 项目，直接 build 一次。如果 3 分钟内能跑通，基本环境就没问题了。我见过有人只配了 JDK 没配 Android SDK，AS 虽然打开不报错，但一编译就崩。

嗯，环境搭建这块其实不难，但细节特别多。你按照上面的步骤，先把 JDK 和 Gradle 装对，再选对 AS 版本，最后把环境变量配好——基本能躲开 90% 的 AGP 配置异常。毕竟后面的问题，大多集中在 build 脚本语法和依赖冲突上，那才是真正的硬仗。