遵循Room官方教程集成时构建报错，启用KSP编译器则正常的问题

按照Android官方Room集成教程完成组件集成后，构建项目时抛出以下错误：

Entity class must be annotated with @Entity

Entities and POJOs must have a usable public constructor. You can have an empty constructor or a constructor whose parameters match the fields (by name and type).

An entity must have at least 1 field annotated with @PrimaryKey

Schema export directory is not provided to the annotation processor so we cannot export the schema. You can either provide `room.schemaLocation` annotation processor argument OR set exportSchema to false.

相关代码片段 #

Entity代码：

@Entity(tableName = "app")
class App(@PrimaryKey val id: Long, val name: String)

Dao代码：

@Dao
interface AppDao {

    @Insert
    suspend fun insertApp(app: App)

}

Database代码：

@Database(
    entities = [AppDao::class],
    version = 1
)
abstract class MyDatabase : RoomDatabase() {
    abstract fun appDao(): AppDao
}

现象说明 #

取消注释ksp(libs.androidx.room.compiler)依赖后，构建不再报错，但不清楚问题根源及完整解决方式。

使用的库版本：

hilt-android = "2.46"
junit = "4.13.2"
kotlin = "1.8.20"
kotlin-ksp = "1.8.20-1.0.11"
room = "2.6.0-alpha01"

问题根源与解决步骤 #

1. 修复Database实体引用错误
   Database类的@Database注解中，entities参数应该传入实体类App::class，而非Dao接口AppDao::class。错误地将Dao当成实体类传入，导致Room对其进行实体校验，触发了前三条错误。修正后的Database代码：

   @Database(
       entities = [App::class],
       version = 1
   )
   abstract class MyDatabase : RoomDatabase() {
       abstract fun appDao(): AppDao
   }
   

2. 确保Room编译器依赖正确配置
   Room基于注解处理器工作，Kotlin项目需要通过KSP引入room-compiler依赖。之前注释掉该依赖时，注解处理器未生效，导致Room无法识别@Entity、@PrimaryKey等注解，从而抛出实体相关错误。必须保留ksp(libs.androidx.room.compiler)依赖，确保注解处理器正常运行。

3. 处理Schema导出警告
   针对最后一条错误，有两种解决方式：

   • 方式一：在@Database注解中添加exportSchema = false（适合开发阶段或不需要保留Schema历史的场景）：

     @Database(
         entities = [App::class],
         version = 1,
         exportSchema = false
     )
     abstract class MyDatabase : RoomDatabase() {
         abstract fun appDao(): AppDao
     }
     

   • 方式二：配置Schema导出目录（适合需要跟踪数据库版本变更的场景）：
     在模块的build.gradle.kts中添加如下配置：

     android {
         defaultConfig {
             ksp {
                 arg("room.schemaLocation", "$projectDir/schemas")
             }
         }
     }
     

     同时手动在项目根目录创建schemas文件夹，Room会自动将数据库Schema文件导出到该目录。

内容的提问来源于stack exchange，提问作者Captain Jacky