📚 课程目录第2章开发环境准备

2. 开发环境准备

Compose测试环境的稳定性直接依赖于底层工具链的版本对齐。本章从原理出发，梳理JDK、Android Studio、Gradle与Kotlin之间的依赖关系，给出经过验证的版本组合，并提供配置验证步骤与常见错误排查方法。

一、JDK版本要求

Compose编译器（Compose Compiler）作为Kotlin编译器插件，其内部使用了大量JDK API。AGP（Android Gradle Plugin）7.x及更高版本要求JDK 11以上，而部分Compose Compiler版本在JDK 17下可获更优的增量编译性能。下表列出典型版本对应关系：

Compose BOM 版本	最低 JDK	推荐 JDK	备注
2023.01.00 – 2023.08.00	11	11	Android Studio Giraffe 默认捆绑 JDK 11
2023.10.00 – 2024.02.00	11	17	Gradle 8.4+ 建议使用 JDK 17
2024.05.00 及以上	17	17 或 21	Kotlin 2.0+ 编译器要求 JDK 17

实践建议：统一安装 JDK 17。它兼容所有当前主流 Compose 版本，且能避开某些 JDK 11 下 AGP 8.2 的 JVM 参数解析 bug。

二、Android Studio与SDK配置

推荐使用 Android Studio Giraffe（2022.3.1）或更高版本。低于此版本的 Studio 无法自动识别 Compose 模板中的 Kotlin 2.0+ 语法。安装后需在 SDK Manager 中确认以下组件：

Android SDK Platform 34（或项目 targetSdk 对应版本）
Android SDK Build-Tools 34.0.0
NDK (Side by side) 25.2.9519653（若项目中包含 native 代码或 C/C++ 测试）

通过 File > Settings > Languages & Frameworks > Kotlin 查看内置 Kotlin 插件版本，建议与项目实际使用的 Kotlin 版本相差不超过一个次版本号。

三、Gradle版本与Kotlin兼容性

Compose 编译器版本与 Kotlin 版本严格绑定，而 Kotlin 版本又与 Gradle 和 AGP 存在耦合。错误的版本组合会导致类冲突或编译崩溃。以下为经过 CI 验证的稳定组合：

Kotlin 版本	Compose Compiler 版本	AGP 版本	Gradle 版本
1.8.22	1.4.8	8.1.4	8.2
1.9.22	1.5.10	8.2.2	8.4
2.0.0	2.0.0	8.4.0	8.6
2.0.21	2.0.21	8.5.0	8.7

在项目根目录 build.gradle.kts 中声明 Kotlin 和 Compose 插件时，应显式指定版本号：

// 项目级 build.gradle.kts（Kotlin 2.0.21 + Compose Compiler 2.0.21）
plugins {
    id("com.android.application") version "8.5.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.21" apply false
}

// 模块级 build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
}

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 21
        targetSdk = 34
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "2.0.21"  // 显式指定
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.09.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")
    androidTestImplementation(platform("androidx.compose:compose-bom:2024.09.00"))
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
}

注意：Kotlin 2.0.0+ 起，Compose编译器插件从 Kotlin 仓库独立为 org.jetbrains.kotlin.plugin.compose，不再需要 kotlinCompilerExtensionVersion（但保留向下兼容）。若使用 2.0.21，建议同时声明两种方式以避免混淆。

四、环境验证流程

配置完成后，建议执行以下命令验证所有工具链就绪：

# 1. JDK 版本检查
java -version
# 输出示例：openjdk version "17.0.12" 2024-07-16 LTS

# 2. Gradle 版本检查
./gradlew --version
# 关注 Gradle 和 Kotlin DSL 版本

# 3. 检查 Gradle 守护进程使用的 JDK
./gradlew --stop
./gradlew --info | grep "JVM"
# 应显示正确 JDK 路径

# 4. 项目编译与依赖解析
./gradlew dependencies --configuration debugRuntimeClasspath
# 确认 compose-bom 和 kotlin-stdlib 版本无冲突

若一切正常，执行一个简单的 Compose UI 测试验证运行时环境：

./gradlew :app:connectedDebugAndroidTest
# 或仅运行指定 test 类
./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.example.MyComposeTest

五、常见错误与解决

“Unsupported Java. Your build is currently configured to use Java 11.0.x and Gradle 8.6 requires Java 17 or later.”
解决方案：设置 JAVA_HOME 为 JDK 17 路径，或修改 studio.vmoptions 中 jdk 指向。
“Cannot inline bytecode built with JVM target 1.8 into bytecode that is being built with JVM target 17”
原因：某些库（如旧版 Compose Compiler）针对 JVM 1.8 编译。在 build.gradle.kts 中强制指定 JVM 目标：
```
kotlin {
    jvmToolchain(17)
}
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}
```
“Kotlin version mismatch: expected 1.9.22, actual 2.0.21”
通常由 BOM 版本与 Compose Compiler 版本不一致导致。检查 composeOptions.kotlinCompilerExtensionVersion 是否与 BOM 中的 Compose Compiler 匹配，或改用 kotlinPluginCompose 自动对齐。
“No service of type 'org.jetbrains.kotlin.gradle.utils.KotlinEnvironmentProvider' available”
多见于 Gradle 8.5+ 与较旧 Kotlin 插件。更新 Kotlin 插件至 2.0.20+ 或降级 Gradle 至 8.4。

关键检查点：每次修改版本号后务必执行 ./gradlew clean 并重启 Gradle 守护进程，避免缓存污染导致伪错误。

六、性能与稳定性优化

使用 Gradle 配置缓存（org.gradle.configuration-cache=true）可加快增量编译，首次构建后二次启动减少 40~60% 配置时间。
为 JVM 守护进程分配足够内存：在 gradle.properties 中写入 org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m，避免 Compose 编译时因内存不足导致 OOM。
若使用 Kotlin 2.0+ Compose Compiler，启用 K2 模式（默认开启）以获得更快的类型解析；但注意与某些 KSP 插件存在冲突，需测试验证。

将 Compose BOM 依赖统一在 libs.versions.toml 中管理，降低版本分散风险：

# gradle/libs.versions.toml
[versions]
kotlin = "2.0.21"
compose-bom = "2024.09.00"
agp = "8.5.0"

[libraries]
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
compose-ui = { group = "androidx.compose.ui", name = "ui", version.ref = "compose-bom" }
compose-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4", version.ref = "compose-bom" }

完成以上配置后，你的开发环境已满足运行大部分 Compose 测试的基本要求。下一维度将聚焦测试框架选型与项目结构划分。