第1章 迁移环境搭建与工具链准备

从 Room 迁移到 DataStore 的第一步，不是修改一行代码，而是搭建一套干净、版本对齐的构建环境。环境混乱会导致依赖冲突、API 不可用、运行时崩溃三大问题，后续 29 章的所有实操都将建立在当前这一章的工具链基础上。本章的目标是：在你本地 IDE 中复现一份经过验证的、可直接启动迁移工作的环境清单。

1.1 环境总览

下表列出迁移工程所需的全部工具及推荐版本。版本号以 2025 年初稳定版为准，后续章节的代码示例均在此版本组合下验证通过。

1.2 Android Studio 与 JDK 配置

Android Studio Ladybug 内置了 JDK 17，但仍建议显式指定项目 JDK 路径，避免因 IDE 升级导致默认 JDK 回退。

# Windows 局部变量（可选，用于命令行编译）
set JAVA_HOME=C:\Program Files\Android\Android Studio\jbr

# macOS / Linux
export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

在 gradle.properties 中锁定守护进程的 JDK 版本：

# 强制 Gradle 使用 JDK 17
org.gradle.java.home=/Applications/Android Studio.app/Contents/jbr/Contents/Home

验证 JDK 版本是否生效：

./gradlew -version

输出示例中应包含 JVM: 17.0.12 字样。如果显示 11.0.x 或 1.8.x，说明 JAVA_HOME 或 gradle.properties 配置未生效，需要检查路径是否正确。

1.3 Gradle 与 AGP 配置

在项目根目录的 settings.gradle.kts 中声明依赖仓库和插件版本目录：

// settings.gradle.kts
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "RoomToDataStore"

在根 build.gradle.kts 中声明 AGP 和 Kotlin 插件版本：

// 根 build.gradle.kts
plugins {
    id("com.android.application") version "8.5.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.24" apply false
    id("com.google.devtools.ksp") version "1.9.24-1.0.20" apply false
}

1.4 DataStore 依赖声明

在模块级 app/build.gradle.kts 中添加 DataStore 依赖。同时保留 Room 依赖作为迁移源，通过 ksp 处理 Room 注解。

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

android {
    namespace = "com.example.roomtodatastore"
    compileSdk = 34
    defaultConfig {
        applicationId = "com.example.roomtodatastore"
        minSdk = 24
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // ── Room（迁移源） ──
    implementation("androidx.room:room-runtime:2.6.1")
    implementation("androidx.room:room-ktx:2.6.1")
    ksp("androidx.room:room-compiler:2.6.1")

    // ── DataStore（迁移目标） ──
    implementation("androidx.datastore:datastore-preferences:1.1.1")

    // ── 可选：DataStore 纯文件存储（用于自定义序列化） ──
    // implementation("androidx.datastore:datastore-core:1.1.1")

    // ── 协程（DataStore 异步读写依赖） ──
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")
}

同步完成后，在 Android Studio 的 Gradle 面板中展开 app → Tasks → other，双击 dependencies 查看依赖树，确认 datastore-preferences 和 room-runtime 均存在且版本正确。

1.5 工具链架构与数据流关系

下图展示了从 Room 迁移到 DataStore 过程中，各工具组件之间的依赖关系以及数据流向。理解这一架构有助于后续章节定位问题边界。

1.6 常见环境错误与修复

1.7 验证环境

执行以下命令一次性检查构建完整性：

# 清理缓存并重新编译
./gradlew clean assembleDebug

# 如果编译成功，且控制台无 "datastore" 或 "room" 相关红色错误，
# 则环境搭建完成，可以进入第 2 章：数据模型分析与迁移策略制定。