2. 项目环境搭建：Android Studio版本、Gradle依赖配置、minSdkVersion、KSP插件配置

本章围绕《Room与WorkManager持久化队列案例》的技术栈环境搭建展开。正确选择IDE版本、Gradle工具链、Kotlin符号处理（KSP）插件以及最低SDK版本，是项目能顺利编译、运行和调试的基础。我们将按照“工具选择 → 项目级配置 → 模块级配置 → 同步验证”的流程，逐步完成环境搭建，并指出常见偏差。

2.1 技术栈依赖关系

Room和WorkManager都依赖注解处理器或符号处理器来生成代码；Room从2.6.0起正式推荐使用KSP替代kapt以提升编译速度。整体技术栈层次如下：

2.2 Android Studio 版本要求

建议使用 Android Studio Hedgehog (2023.1.1) 及以上版本，以原生支持KSP插件自动发现和Kotlin 2.0+。旧版本可能需要手动指定KSP插件版本。可在 Help → About 中查看当前版本。

2.3 项目级 Gradle 配置

在项目根目录的 build.gradle.kts（或 build.gradle）中声明KSP插件依赖和仓库：

// 项目根 build.gradle.kts
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

版本对齐说明：KSP 版本号需与项目使用的 Kotlin 版本严格匹配。Kotlin 1.9.22 对应的 KSP 为 1.9.22-1.0.17。

2.4 模块级 build.gradle.kts 配置

2.4.1 应用插件

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

2.4.2 minSdkVersion & compileSdk

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

    defaultConfig {
        applicationId = "com.example.roomworkmanager"
        minSdk = 21          // 覆盖绝大多数设备，Room 支持的最低版本
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

🔹 minSdk 选择建议：若项目仅需支持 Android 8.0+（API 26），建议设为 26，可省略部分兼容代码。本课程使用 minSdk 21 以覆盖更广设备，同时关注 WorkManager 的最低要求。

2.4.3 Room & WorkManager 依赖

dependencies {
    // Room
    val roomVersion = "2.6.1"
    implementation("androidx.room:room-runtime:$roomVersion")
    implementation("androidx.room:room-ktx:$roomVersion")
    ksp("androidx.room:room-compiler:$roomVersion")

    // WorkManager
    val workVersion = "2.9.0"
    implementation("androidx.work:work-runtime-ktx:$workVersion")

    // 其他通用依赖
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}

2.5 KSP 配置细节

KSP 插件在 build.gradle.kts 中通过 ksp {} 可配置选项（非必须），例如开启增量编译：

ksp {
    arg("room.schemaLocation", "$projectDir/schemas") // 导出 Room 数据库 schema
    arg("room.incremental", "true")                    // 启用增量处理
}

导出的 schema 文件可用于版本迁移测试和文档生成。

2.6 配置核对清单

2.7 同步与验证

1. File → Sync Project with Gradle Files，观察 Build 窗口无红色错误。
2. 在终端执行 ./gradlew assembleDebug 确认编译通过。
3. 检查生成的 Java/KSP 代码（位于 build/generated/ksp/debug/ 内），应有 Room 的类如 AppDatabase_Impl。
4. 运行一次项目到模拟器或真机，确保无运行时崩溃。

2.8 常见错误及解决

• 错误：ksp plugin version mismatch
  检查 Kotlin 版本和 KSP 版本是否匹配，参考 KSP Release。
• 错误：Room: Cannot find getter for field
  通常是因为 Room 实体类未使用 @Entity 注解，或 Room 编译器未通过 KSP 注册。确认 ksp(...) 依赖是否添加。
• 错误：Duplicate class
  Room 和 WorkManager 都依赖 androidx.lifecycle，检查是否版本冲突，建议统一 lifecycle 版本。
• 错误：FAILURE: Build failed with an exception (Gradle)
  优先检查 gradle-wrapper.properties 中 Gradle 版本是否与 AGP 兼容（AGP 8.2.x 需要 Gradle 8.2+）。

2.9 性能与稳定性优化预览

环境搭建阶段的优化点：

• 启用 Gradle 配置缓存（gradle.properties 中设置 org.gradle.configuration-cache=true），减少重复配置解析时间。
• 使用 KSP 替代 kapt，后文将演示编译时间对比。
• 限制 Room schema 导出路径，避免占用磁盘空间（通过 room.schemaLocation 指定项目内目录）。

完成本章配置后，项目应具备 Room + WorkManager 联合编译能力。下一环节将创建数据库实体与 DAO 接口。