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

开发环境搭建

说实话，很多人一开始把精力全扑在写代码上，结果环境配不好，编译半小时报错两百行，心态直接崩了。我个人习惯是先花二十分钟把 Android Studio、Gradle 和关键依赖一个个捋清楚，后面写代码才能顺畅。这一章我就带你走一遍我自己的搭建流程，顺便说说我踩过的坑。

1. Android Studio 版本选哪个？

我建议直接用最新稳定版，别用预览版。以前我贪新鲜装过 Canary 版，结果 Room 的 kapt 插件报了个奇怪的错，折腾半天才发现是 IDE 的 AGP 不兼容。现在用 Hedgehog 或 Iguana 都行，API level 至少选 31（Android 12），因为 Compose 1.3+ 很多特性依赖 31 以上的 API。

2. Gradle 配置——几个关键点

很多人复制粘贴 build.gradle 就完事了，但版本号没对齐就会翻车。我个人习惯把版本提取到 gradle.properties 或使用 version catalog。这里看一个 app 模块的 build.gradle.kts 示例：

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp") // 替代 kapt，编译更快
}

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

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

    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8" 
        // 这个版本必须和 kotlin 版本匹配，我踩过坑
    }
}

dependencies {
    // 下面详细讲
}

✨ 我的小技巧：尽量用 ksp 替代 kapt。Room 的编译速度能快一倍，而且错误信息更友好。

3. Compose BOM —— 版本管理省心神器

Compose 组件多，UI、Material3、动画、工具……版本号一个一个写太容易出错了。BOM（Bill of Materials）可以统一管理所有 Compose 库版本。你只需要声明一个 BOM 版本，所有 compose 组件版本都会自动对齐。

在 dependencies 块里加：

dependencies {
    val composeBom = platform("androidx.compose:compose-bom:2024.02.00")
    implementation(composeBom)

    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.ui:ui-graphics")
    implementation("androidx.compose.ui:ui-tooling-preview")
    implementation("androidx.compose.material3:material3")
    debugImplementation("androidx.compose.ui:ui-tooling")
}

说白了，你只要升级 BOM 版本，下面所有 compose 库都会跟着升级，省心又安全。

4. Room 依赖——两步走

Room 需要三个东西：runtime、compiler（用 ksp）、以及 ktx 扩展。我习惯这样写：

dependencies {
    // Room
    implementation("androidx.room:room-runtime:2.6.1")
    implementation("androidx.room:room-ktx:2.6.1")
    ksp("androidx.room:room-compiler:2.6.1")
}

⚠️ 注意：我曾经把 room-compiler 的版本号和 runtime 写成了不同版本，结果编译通过但运行时 DAO 查询直接崩溃。一定要确保所有 Room 相关依赖的版本号完全一致。

5. Kotlin 协程依赖

Room 配合协程才能写出流畅的异步代码。如果你用的是 kotlinx-coroutines-core，还需要 android 协程调度器：

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}

coroutines-android 提供了 Dispatchers.Main，配合 Room 的 suspend 函数，写异步代码就像写同步一样。嗯，这个我之前没加，结果在后台线程更新 UI 直接 crash，加了才解决。

6. 快速版本对照表

下面是我项目中常用版本，你可以根据 AGP 版本微调：

组件	推荐版本	说明
Compose BOM	2024.02.00	统一管理 Compose 全家桶
Room	2.6.1	需配合 ksp 使用
Kotlin	1.9.22	Compose 1.5.x 要求 Kotlin 1.9.x
kotlinx-coroutines	1.7.3	与 Kotlin 版本兼容
AGP	8.2.2	与 Gradle 8.5 搭配
KSP	1.9.22-1.0.17	必须与你 Kotlin 版本匹配

📌 核心原则：所有版本号都要相互兼容。特别是 kotlinCompilerExtensionVersion、Kotlin 版本、KSP 版本这三个，必须一一对齐。官方有一个兼容性表格，我每次升级都会去查一下，避免踩坑。

7. 验证环境是否搭建成功

配置完所有依赖后，执行一次 File → Sync Project with Gradle Files。如果一切顺利，你会看到 BUILD SUCCESSFUL。然后写一个最简单的 Composable 函数试试：

@Composable
fun Greeting(name: String) {
    Text(text = "Hello $name")
}

在模拟器或真机上跑起来，看到 "Hello Room" 就说明环境搞定了。我个人还会再写一个空的 Room DAO 和 Entity，编译一次确保 ksp 没报错。这一步虽然琐碎，但能省掉后面排查的大把时间。