2、开发环境搭建：添加Room依赖、配置KSP/KAPT、Gradle同步与常见问题排查

好，咱们正式开始动手了。这一章说白了就是搭积木——把Room需要的那些依赖和工具链塞进项目里。别小看这一步，我见过不少新手卡在这里，Gradle报错一屏幕，心态直接崩了。嗯，咱们慢慢来，把每一步踩实了。

2.1 准备工作：确认你的Android Studio版本

我个人习惯用最新稳定版的Android Studio。为什么？因为Room的KSP配置对Gradle版本有要求，老版本可能不支持。你可以在 Help → About 里查看版本号。建议用Android Studio Hedgehog（2023.1.1）或更高版本。

另外，确保你的项目已经迁移到了AndroidX。如果你还在用旧的支持库，Room 2.6+会直接报错。怎么检查？打开 gradle.properties，看看有没有这两行：

android.useAndroidX=true
android.enableJetifier=true

没有的话，加上。Jetifier的作用是把第三方库里的旧支持库自动转成AndroidX。我在项目中遇到过几次因为没开Jetifier导致的编译冲突，排查了半天才发现是这个问题。

2.2 添加Room核心依赖

打开模块级的 build.gradle.kts（如果你用Groovy，那就是 build.gradle）。在 dependencies 块里加上Room的依赖。注意，Room的版本号要统一，别混着写。

// 以Kotlin DSL为例
dependencies {
    val roomVersion = "2.6.1"

    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")
    // 如果你需要Room的协程支持（强烈建议加上）
    implementation("androidx.room:room-coroutines:$roomVersion")
}

这里我解释一下：room-runtime 是核心库，room-ktx 提供了Kotlin协程的扩展函数。说白了，没有 room-ktx，你写DAO的时候就得手动处理线程切换，那体验可太糟糕了。

2.3 选择注解处理器：KSP还是KAPT？

这是个大问题。Room需要注解处理器来生成代码（比如DAO的实现类）。以前大家都用KAPT，但KAPT有个毛病——它会把Kotlin代码先转成Java再处理，速度慢得让人抓狂。KSP是Google后来推出的替代方案，直接处理Kotlin源码，编译速度能快2-3倍。

我的建议： 新项目一律用KSP。除非你用的某个第三方库只支持KAPT，否则别回头。

怎么配置KSP？首先在项目级的 build.gradle.kts 里添加KSP插件：

// 项目级 build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

然后在模块级 build.gradle.kts 里应用插件并添加Room的KSP处理器：

// 模块级 build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp") // 应用KSP插件
}

android {
    // ... 你的android配置
}

dependencies {
    val roomVersion = "2.6.1"

    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")

    // 用KSP代替KAPT
    ksp("androidx.room:room-compiler:$roomVersion")
}

注意看，这里用的是 ksp(...) 而不是 kapt(...)。如果你非要用KAPT，那就把 ksp 换成 kapt，同时记得在 plugins 里加上 id("org.jetbrains.kotlin.kapt")。但我还是那句话——能用KSP就别折腾KAPT。

2.4 Gradle同步与常见问题排查

依赖加完了，点一下 Sync Now。嗯，这一步通常不会一帆风顺。我把最常见的几个坑列出来，你遇到了直接对照着查。

错误信息	原因	解决方案
Cannot find symbol class Room	Room依赖没加对，或者版本号写错了	检查 dependencies 里的 room-runtime 是否拼写正确
KSP was not applied	模块级没应用KSP插件	在 plugins 块里加上 id("com.google.devtools.ksp")
Unresolved reference: ksp	项目级没声明KSP插件	在项目级 build.gradle.kts 的 plugins 里加上 apply false 那行
Room cannot find the Database annotation	Kotlin版本和Room版本不兼容	升级Kotlin到1.9.0+，或者降级Room到2.5.x
Duplicate class 错误	同时加了KAPT和KSP的处理器	只保留一个，删掉另一个

我曾经有一次折腾了整整一下午，就是因为KSP版本写成了 1.9.22-1.0.16，而我的Kotlin是 1.9.23。Gradle报错说“不兼容”，我愣是没往版本匹配上想，还以为是依赖冲突。后来去KSP的GitHub页面一看，好家伙，版本号差一个补丁都不行。所以，版本匹配是重中之重。

2.5 验证环境是否搭建成功

依赖配好了，怎么知道Room能不能用？写一个最简单的Entity和DAO，然后编译看看。

先建一个 User.kt：

import androidx.room.Entity
import androidx.room.PrimaryKey

@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String,
    val age: Int
)

再建一个 UserDao.kt：

import androidx.room.Dao
import androidx.room.Insert
import androidx.room.Query

@Dao
interface UserDao {
    @Insert
    suspend fun insert(user: User)

    @Query("SELECT * FROM users")
    suspend fun getAllUsers(): List<User>
}

最后建一个 AppDatabase.kt：

import androidx.room.Database
import androidx.room.Room
import androidx.room.RoomDatabase
import android.content.Context

@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getDatabase(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "app_database"
                ).build()
                INSTANCE = instance
                instance
            }
        }
    }
}

然后点 Build → Make Project。如果编译通过，没有红色波浪线，恭喜你，环境搭好了。如果报错，对照上面的表格排查。

嗯，到这里环境就搭好了。别急着往下走，先确保你的项目能编译通过。我见过太多人一口气把整个项目写完，结果编译报错几百行，根本不知道从哪改起。环境搭建这一步，稳扎稳打最重要。

最后说一句，如果你用的是KAPT，记得在 build.gradle.kts 里加上 kapt { correctErrorTypes = true }。这个配置能让你在编译时看到更详细的错误信息。KSP不需要这个，它默认就做得很好。

---