解决 Android Studio 中使用 Room 时 kapt 和 ksp 的未解析引用错误

问题描述

配置 Android Room 数据库时，在 build.gradle.kts 文件中遇到 "Unresolved reference kapt" 和 "Unresolved reference ksp" 错误。该问题通常发生在新的 Android Studio Kotlin 项目中添加 Room 依赖后，如下图所示：

// 错误代码片段
kapt("androidx.room:room-compiler:$room_version") // Unresolved reference kapt
ksp("androidx.room:room-compiler:$room_version")  // Unresolved reference ksp

根本原因是：

1. 缺少必要的插件声明
2. 未正确处理注解处理器
3. kapt 和 ksp 插件没有正确配置

kapt 和 ksp 详解

kapt (Kotlin Annotation Processing Tool)

• 作用：处理 Java/Kotlin 注解并生成代码
• 适用场景：支持 Java 注解处理器（如 Room, Dagger）
• 特点：兼容性好但构建速度较慢

ksp (Kotlin Symbol Processing)

• 作用：Kotlin 原生的注解处理工具
• 适用场景：专为 Kotlin 设计（如 Room KSP 扩展）
• 特点：构建速度比 kapt 快 2 倍以上

重要说明

不要同时使用 kapt 和 ksp 处理同一个依赖。Room 只能选择其中一种方式！

解决方案

方法一：使用 kapt（推荐新手）

1. 添加 kapt 插件声明： 在 app 模块的 build.gradle.kts 的 plugins 块中添加：

// app/build.gradle.kts
plugins {
    id("kotlin-kapt") // 添加这行
}

2. 配置 Room 依赖： 修改 dependencies 部分（保留 kapt，移除 ksp）：

dependencies {
    // ...其他依赖
    
    val room_version = "2.6.1"
    implementation("androidx.room:room-runtime:$room_version")
    kapt("androidx.room:room-compiler:$room_version") // 仅保留此项
    
    // ...Room的其他依赖
}

3. 项目级配置（可选）： 在项目级 build.gradle.kts 中添加兼容插件：

// 项目级 build.gradle.kts
plugins {
    id("com.android.library") version "8.1.1" apply false
}

方法二：使用 ksp（性能更优）

1. 项目级配置： 在项目级 build.gradle.kts 中声明 ksp 插件：

// 项目级 build.gradle.kts
plugins {
    id("com.google.devtools.ksp") version "1.9.21-1.0.15" apply false // 使用最新版本
}

2. 应用 ksp 插件： 在 app 模块的 build.gradle.kts 中启用 ksp：

// app/build.gradle.kts
plugins {
    id("com.google.devtools.ksp") // 添加此行
}

3. 更新依赖配置： 修改为 ksp 依赖并移除 kapt：

dependencies {
    // ...其他依赖
    
    val room_version = "2.6.1"
    implementation("androidx.room:room-runtime:$room_version")
    ksp("androidx.room:room-compiler:$room_version") // 使用ksp替换kapt
    
    // ...Room的其他依赖
}

版本兼容性提示

请确保 ksp 版本与 Kotlin 版本兼容（查看官方兼容性表）。

常见错误排查

1. 插件应用顺序问题：

   // 正确顺序
   plugins {
       id("com.android.application")
       id("org.jetbrains.kotlin.android")
       id("com.google.devtools.ksp") // 在Android和Kotlin后添加
   }

2. 版本冲突解决：

   • 确保所有 Android Gradle 插件版本一致（如 8.1.1）
   • 在 settings.gradle.kts 中启用插件管理：

     pluginManagement {
         repositories {
             google()
             mavenCentral()
             gradlePluginPortal()
         }
     }

3. 构建缓存清理： 修改配置后执行：

   ./gradlew clean build --refresh-dependencies

总结

当遇到 kapt/ksp 未解析引用问题时：

1. 首选 ksp 方案以获得更快的构建速度
2. 仔细检查插件声明位置：
   • kapt 只需在 app 模块声明
   • ksp 需要项目级声明版本 + app 模块启用
3. 不要混合使用 kapt 和 ksp
4. 完成后同步 Gradle（Android Studio 右上角 "Sync Now"）

最新配置请参考 Room 官方文档 和 KSP 官方文档。