第2章 迁移环境搭建：项目依赖配置、Gradle 版本要求、Kotlin 协程支持、DataStore 版本选择

在开始从 SharedPreferences (SP) 向 DataStore 迁移之前，必须搭建一套稳定的编译与运行时环境。环境配置直接影响迁移代码能否正常编译、协程能否正确调度以及 DataStore 实例的线程安全性。本章围绕 Gradle 版本约束、Android Gradle Plugin (AGP) 兼容性、Kotlin 与协程依赖、DataStore 库选型等核心维度展开，并给出经过验证的依赖配置模板。

2.1 环境全景

迁移环境涉及四个层次：构建工具层（Gradle / AGP）、语言层（Kotlin / 协程）、存储库层（DataStore）以及迁移辅助层（数据校验与测试工具）。下图展示了各组件之间的依赖关系与版本匹配要点：

2.2 Gradle 版本要求

DataStore 库从 1.0.0 起要求 compileSdk 31+，而 Gradle 版本直接影响构建工具的依赖解析能力。下表列出推荐的最低版本与测试过的稳定组合：

组件	最低版本	推荐版本	说明
Gradle	7.0	7.4 或 8.0	支持 Java 11 及 AGP 7.x
Android Gradle Plugin	7.0.0	7.4.2	与 DataStore 1.0+ 配合良好
Kotlin 编译器	1.5.0	1.8.22	需内置协程支持（1.6+ 协程库）
compileSdk	31	34	DataStore API 在此 SDK 上稳定

2.3 Kotlin 协程支持

DataStore 的所有读写操作都挂起（suspend）或返回 Flow，因此项目必须显式依赖 kotlinx-coroutines-android 并将 Kotlin 编译器版本提升至 1.5.0 以上。在模块级 build.gradle 中启用协程支持：

android {
    kotlinOptions {
        jvmTarget = "1.8"
    }
}
dependencies {
    // 核心协程依赖（必须）
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4"
    // 测试协程依赖（可选，但强烈推荐）
    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.4"
}

2.4 DataStore 版本选择

DataStore 目前提供两个分支：Preferences DataStore（键值对，对标 SP）和 Proto DataStore（类型化存储）。迁移场景通常选择 Preferences 分支，其版本演进如下：

版本	API 稳定性	最低 compileSdk	备注
1.0.0	正式发布	31	首个稳定版，可用于生产
1.0.2	正式发布	31	修复了某些 Android 12 上的异常
1.1.0	正式发布	33	新增 edit() 的同步异常处理

2.5 完整依赖配置模板

在模块级 build.gradle.kts 中整合所有依赖（以下为 Kotlin DSL 示例）：

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android") version "1.8.22"
}

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 21
        targetSdk = 34
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
}

dependencies {
    // DataStore Preferences
    implementation("androidx.datastore:datastore-preferences:1.0.2")

    // Kotlin Coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")

    // 单元测试
    testImplementation("junit:junit:4.13.2")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.6.4")
    testImplementation("androidx.test:core:1.5.0")
    testImplementation("androidx.arch.core:core-testing:2.2.0")
}

2.6 调试与常见错误排查

• 错误 1：Module was compiled with an incompatible version of Kotlin → 检查 Kotlin 插件版本与依赖库的协程版本是否一致。建议统一 Kotlin 版本为 1.8.x。
• 错误 2：Cannot resolve symbol 'DataStore' → 确认已添加 androidx.datastore:datastore-preferences 依赖，并执行了 Gradle Sync。
• 错误 3：java.lang.NoClassDefFoundError: kotlinx/coroutines/flow/Flow → 缺少协程运行时代理，请添加 kotlinx-coroutines-android。
• 性能关键点：在 AndroidManifest.xml 中不要为 DataStore 操作配置 android:process 隔离进程，否则协程作用域会失效，导致数据不一致。

2.7 环境验证清单

完成配置后，建议执行以下快速验证步骤：

1. 运行 ./gradlew assembleDebug 确认编译通过。
2. 在单元测试中创建 DataStore 实例并写入简单键值，检查无异常。
3. 确认协程测试使用 runTest 或 TestCoroutineDispatcher 能正确挂起。