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

2. 开发环境搭建：JDK版本选择、Android Studio配置、Gradle插件设置

Compose 项目高度依赖现代 JVM 语言特性与 Gradle 构建体系。本章从底层原理出发，逐步拆解 JDK、Android Studio、Gradle 插件三个关键环节的选型逻辑与配置流程，并提供可复用的配置模板与常见错误解决路径。

2.1 JDK 版本选择

2.1.1 核心原则

Compose 编译器需要 Kotlin 1.5+ 配合 JDK 11+ 才能正确生成元数据。JDK 版本过低会导致 Unsupported class file major version 错误，过高则可能触发 Gradle 兼容性警告。生产环境推荐使用 JDK 17 LTS，兼顾性能、安全与生态支持。

2.1.2 版本对比

JDK 版本	最低 Compose 版本	状态	推荐场景
8	不兼容	已废弃	——
11	1.0.0	兼容，但 AGP 8.0+ 会产生警告	遗留项目迁移
17	1.2.0	官方推荐	新项目、CI/CD
21	1.6.0	预览支持	试用新特性

2.1.3 安装与验证

在 macOS / Linux 中设置 JAVA_HOME 环境变量：

export JAVA_HOME=/usr/local/jdk-17.0.12
export PATH=$JAVA_HOME/bin:$PATH

验证安装：

java --version
# 输出应包含 openjdk 17.0.12 2024-07-16 LTS

⚠ 常见错误：Windows 用户务必在系统环境变量中将 JAVA_HOME 的路径置于 PATH 最前方，避免多个 JDK 版本冲突导致 Gradle 识别到 JDK 8。

2.2 Android Studio 配置

2.2.1 版本选择

官方 AGP（Android Gradle Plugin）与 Android Studio 有严格的版本映射。以下为当前稳定版对照：

Android Studio 版本	推荐 AGP 版本	Kotlin 插件版本
Hedgehog (2023.1.1)	8.2.x	1.9.22
Iguana (2023.2.1)	8.3.x	1.9.23
Jellyfish (2024.1.x)	8.4.x	2.0.0+

安装时选择 Canary / Beta 通道 可提前获取最新 Compose 支持，但生产项目建议使用 Stable 通道。

2.2.2 必要组件

Android SDK Platform 34（或项目对应的 targetSdk）
Android SDK Build-Tools 34.0.0
Kotlin Plugin（内置，但版本需与项目匹配）
Compose 预览插件（Settings → Plugins → Android Studio 内默认启用）

2.2.3 虚拟设备（AVD）配置

Compose 强烈依赖 GPU 渲染，需创建 API 33+ 的 x86_64 镜像并启用 Enable Device Frame 以获得真实的预览体验。

💡 调试技巧：若预览时出现 “Render problem”，请在 AVD 设置中开启 “Vulkan” 渲染器，并确保 SDK 目录下包含 system-images/android-34/google_apis_playstore/x86_64。

2.3 Gradle 插件设置

2.3.1 核心依赖坐标

在项目级 build.gradle.kts 中声明插件版本：

plugins {
    id("com.android.application") version "8.4.1" apply false
    id("org.jetbrains.kotlin.android") version "2.0.10" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.10" apply false
}

2.3.2 App 模块配置

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

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

    defaultConfig {
        minSdk 24
        targetSdk 34
    }

    buildFeatures {
        compose true
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")
}

2.3.3 关键参数说明

参数	作用	推荐值
`kotlin.plugin.compose`	独立 Compose 编译器插件（Kotlin 2.0+ 必须）	版本与 Kotlin 插件一致
`compose BOM`	统一管理 Compose 库版本	最新稳定版
`minSdk`	Compose 要求最低 API 21，推荐 24+	24

  📌 性能优化：启用 R8 混淆时，务必保留 Compose 元数据：

  -keep class androidx.compose.** { *; }

  并在 gradle.properties 中添加：

  android.enableR8.fullMode=true

2.4 环境验证流程图

下图展示了从零开始搭建 Compose 开发环境的完整路径，每个验收节点均包含检查命令或错误排查入口。

2.5 常见错误与修复

错误现象	根本原因	解决方案
`Unsupported class file major version 65`	JDK 版本 > 17 与 Gradle 8.4 不兼容	降级 JDK 至 17 或升级 Gradle 8.7+
`Kotlin Compose compiler plugin not found`	缺少 `org.jetbrains.kotlin.plugin.compose` 插件	在 project 级 plugins 中添加，版本与 Kotlin 一致
`Android Studio preview keeps loading`	GPU 模拟器驱动异常	在 AVD 设置中切换软件渲染并重启 Studio
`AGP 8.4 requires Java 17+`	JAVA_HOME 指向 JDK 11	修改环境变量，卸载其他 JDK 版本

2.6 部署与持续集成

在 CI 环境中（如 GitHub Actions），建议使用 sdkmanager 预装指定 AGP 与 Compose BOM 缓存，避免每次构建下载依赖。示例 GitHub Actions 关键片段：

- name: Setup JDK 17
  uses: actions/setup-java@v4
  with:
    distribution: 'temurin'
    java-version: '17'

- name: Setup Android SDK
  uses: android-actions/setup-android@v3
  with:
    api-level: 34
    build-tools: 34.0.0

- name: Build Compose project
  run: ./gradlew assembleDebug --no-daemon

💡 稳定性优化：在 gradle.properties 中增加 org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m 以加速大型 Compose 项目的增量编译。