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

2. 开发环境搭建：配置 Android Studio、Compose BOM、Kotlin 版本、依赖声明

搭建一套稳定、可复现的 Compose 开发环境是支付 UI 组件适配的基础。本章从 Android Studio 版本确认、JDK 与 Kotlin 对齐、Compose BOM 版本锁定到模块级依赖声明，逐步拆解每一步的配置要点与常见陷阱。

2.1 环境总览与版本对照

Compose 对工具链版本有严格耦合关系，以下为 2024 年稳定推荐的组合：

组件	推荐版本	说明
Android Studio	Hedgehog (2023.1.1) 或更高	内置 Compose 预览支持；低于 Arctic Fox 无法使用 Compose
JDK	17（建议使用 Embedded JDK）	Gradle 8+ 依赖 JDK 17；AGP 8.x 强制 JDK 17
Kotlin	1.9.22（与 Compose Compiler 1.5.10 匹配）	Kotlin 版本需要与 Compose Compiler 严格兼容
AGP (Android Gradle Plugin)	8.2.2	配合 Gradle 8.4+，支持 Compose 编译优化
Compose BOM	2024.02.00	统一管理 Compose 各库版本，减少手动同步

版本不兼容陷阱：Kotlin 1.9.0 以下版本无法编译 Compose Compiler 1.5.x；使用 BOM 后仍然需要手动设置 kotlinCompilerExtensionVersion，该属性必须与 Kotlin 版本匹配。错误配置会导致“不兼容的 Kotlin 编译器版本”编译失败。

2.2 Android Studio 与 JDK 配置

从 Android Studio 8.0（即 Hedgehog 版本）开始，推荐使用自带的 Embedded JDK（版本 17）。手动切换 JDK 路径可在 File → Project Structure → SDK Location 中指定。

验证 JDK 版本：在终端运行 java -version 确认输出为 openjdk version "17.0.x"。若使用 Embedded JDK，路径通常位于 /Applications/Android Studio.app/Contents/jbr/Contents/Home（macOS）或 C:\Program Files\Android\Android Studio\jbr（Windows）。

2.3 项目级 Gradle 配置：Kotlin 版本与 BOM

在项目根目录的 build.gradle.kts 中声明 Kotlin 版本和 Compose BOM 的 Maven 仓库。以下为标准配置：

// build.gradle.kts (Project级)
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

allprojects {
    repositories {
        google()
        mavenCentral()
        // 如果使用 Jetpack Compose 夜间快照，可添加 snapshots 仓库
        // maven { url = uri("https://androidx.dev/snapshots/builds/...") }
    }
}

2.4 模块级 Gradle 配置：Compose Compiler 与依赖

在 app/build.gradle.kts 中启用 Compose，并声明 BOM 及具体库：

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.payuicomponent"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.payuicomponent"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // Compose BOM：统一版本
    val composeBom = platform("androidx.compose:compose-bom:2024.02.00")
    implementation(composeBom)

    // 核心 Compose 库（版本由 BOM 控制）
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-graphics")
    implementation("androidx.compose.ui:ui-tooling-preview")
    implementation("androidx.compose.foundation:foundation")
    implementation("androidx.compose.material3:material3")

    // 支付 UI 组件常用辅助库（需手动指定版本或通过 BOM 扩展）
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
    implementation("androidx.activity:activity-compose:1.8.2")

    // Debug 编译时预览与布局检查
    debugImplementation("androidx.compose.ui:ui-tooling")
    debugImplementation("androidx.compose.ui:ui-test-manifest")
}

关键字段解析：

kotlinCompilerExtensionVersion：必须与 Kotlin 1.9.22 匹配，对应 Compose Compiler 1.5.10。不同 Kotlin 版本对应的编译器版本可在官方兼容表中查询。
composeBom：BOM 会锁定 ui、foundation、material3 等版本的版本号。若需覆盖某库，可在 BOM 声明之后单独指定版本。
lifecycle-runtime-compose 和 activity-compose：它们是 Compose 与 Activity 生命周期集成的关键，虽不由 BOM 管理，但需保证与目标SDK兼容。

2.5 Gradle 属性与 Compose 编译优化

在 gradle.properties 中开启 Compose 增量编译和代码缓存，提升构建速度：

# gradle.properties
android.useAndroidX=true
kotlin.code.style=official
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
# Compose 编译优化
android.compose.enabled=true
android.compose.compiler.reporting=true
android.compose.compiler.metricsDestination=../compose-metrics

2.6 常见错误与解决方案

错误现象	根因	解决措施
“Unsupported Kotlin version: 1.9.0”	Compose Compiler 1.5.10 要求 Kotlin ≥ 1.9.22	升级 Kotlin 到 1.9.22，同步 Compose Compiler 版本
“Cannot inline bytecode built with JVM target 17 into bytecode being built”	Kotlin 或 Java 编译目标未统一到 17	在 `compileOptions` 和 `kotlinOptions` 中都设置 jvmTarget=17
“Failed to resolve: androidx.compose:compose-bom:2024.02.00”	Maven 仓库未添加 google() 或 mavenCentral()	在项目级 `build.gradle.kts` 的 `allprojects` 中补全仓库
“Preview is not available”	Compose 预览依赖 `ui-tooling-preview` 未引入，或 Kotlin 编译器扩展版本不匹配	确保 `implementation("androidx.compose.ui:ui-tooling-preview")` 以及 Compose Compiler 版本正确

2.7 开发环境组件关系图

下图展示了从 Android Studio 到最终支付 UI 组件可运行的完整依赖链路，帮助理解各环节的版本对齐关系：

快速验证环境：配置完成后，在 app/src/main/java/…/MainActivity.kt 中写一个最小的 Composable 函数并使用 @Preview 注解，若 Android Studio 的 Preview 面板正常渲染，说明开发环境搭建成功。常见验证代码片段如下：

@Preview(showBackground = true, widthDp = 360)
@Composable
fun PaymentCardPreview() {
    Text("开发环境就绪", style = MaterialTheme.typography.headlineMedium)
}