📚 课程目录第2章开发环境搭建与依赖配置

2. 开发环境搭建与依赖配置

本章搭建完整的开发环境，确保 Android Studio、Gradle 及各库版本兼容。正确配置依赖是后续实现持久化队列与 WorkManager 协作的基础。

2.1 环境要求

工具 / 参数	推荐版本	说明
Android Studio	Hedgehog (2023.1.1) 或更高	内置 AGP 8.2+，支持 KSP
Gradle	8.2 以上	配合 AGP 8.x 使用
JDK	17	Android Studio 内置，也支持手动配置
minSdk	26 (Android 8.0)	WorkManager 最低要求 14，推荐 26 以使用 JobScheduler
targetSdk	34 或当前稳定版	确保运行时权限和后台限制正确

提示：minSdk 若低于 26，WorkManager 会回退到 AlarmManager + BroadcastReceiver，长期任务可靠性下降。实战项目建议从 26 起步。

2.2 Gradle 仓库与插件版本

在项目级 settings.gradle.kts 中添加必要仓库（已默认包含 google() 和 mavenCentral()），确保能拉取最新依赖。

// settings.gradle.kts
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

项目级 build.gradle.kts 声明插件版本（以 KSP 为例，Room 推荐使用 KSP 而非 kapt，提升编译速度）：

// project/build.gradle.kts
plugins {
    id("com.android.application") version "8.2.2" apply false
    id("com.google.devtools.ksp") version "1.9.22-1.0.17" apply false
}

2.3 模块级依赖注入

在 app 模块的 build.gradle.kts 中引入 Room、WorkManager 和 Moshi 的依赖。同时启用 KSP 作为 Room 的注解处理器。

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

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

    defaultConfig {
        applicationId = "com.example.persistentqueue"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

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")

    // Moshi
    val moshiVersion = "1.15.1"
    implementation("com.squareup.moshi:moshi-kotlin:$moshiVersion")
    ksp("com.squareup.moshi:moshi-kotlin-codegen:$moshiVersion")

    // Coroutines (WorkManager 依赖)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")
}

版本陷阱：Room 2.6.x 要求 Kotlin 1.9.0+，WorkManager 2.9.x 要求 AndroidX Lifecycle 2.6+。务必同步检查 Kotlin 插件版本。若编译报错 ClassNotFoundException: androidx.room.…，请确认 KSP 配置正确且已应用插件。

2.4 各库版本兼容性速查

库	推荐版本	最小 Kotlin 版本	配合 KSP 支持
Room	2.6.1	1.9.0	是
WorkManager	2.9.0	1.8.0	否（无注解处理）
Moshi	1.15.1	1.8.0	是 (moshi-kotlin-codegen)
Kotlin Coroutines	1.8.0	—	—

2.5 搭建流程示意

下图概括本章搭建过程：从 Android Studio 创建项目 → 配置 Gradle 仓库与插件 → 注入 Room/WorkManager/Moshi 依赖 → 构建成功。每个步骤对应清晰的依赖注入关系。

关键验证：配置完成后，执行 ./gradlew :app:dependencies 可查看所有传递依赖树，确认 Room、WorkManager、Moshi 均以绿色显示且无冲突。若存在版本冲突，可强制指定版本：

// 在 dependencies 块内
implementation("androidx.room:room-runtime:2.6.1") {
    force = true
}