第3章 项目环境搭建与依赖配置

本章聚焦 WorkManager 与 Kotlin 协程结合开发所需的环境准备与 Gradle 依赖配置。正确搭建开发环境是后续所有案例运行的基础，版本不匹配将直接导致编译失败或运行时异常。

3.1 环境要求概览

以下表格列出开发环境各组件的最低版本与推荐版本，所有版本均经过官方兼容性验证。

3.2 Gradle 依赖配置步骤

在 Android 项目中集成 WorkManager 与协程，需按以下三步完成依赖声明：

1. 配置项目级 build.gradle — 声明 AGP 插件版本与 Kotlin 插件版本，统一管理仓库地址。
2. 配置模块级 build.gradle — 添加 work-runtime-ktx 与 kotlinx-coroutines-android 依赖，并设置 SDK 版本。
3. 同步 Gradle — 点击 Sync Now 下载依赖，并检查版本兼容性错误。

3.3 版本兼容性矩阵

以下矩阵列出 AGP、Gradle、Kotlin 与 JDK 之间的强制配套关系，以及 WorkManager 的推荐基线：

3.4 完整配置文件示例

以下为使用 Kotlin DSL 的项目级与模块级 build.gradle 配置：

3.4.1 项目级 build.gradle.kts

// 项目级 build.gradle.kts
plugins {
    // AGP 插件版本
    id("com.android.application") version "8.2.2" apply false
    id("com.android.library") version "8.2.2" apply false
    // Kotlin 插件版本
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

// 统一仓库与任务配置
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

tasks.register("clean", Delete::class) {
    delete(rootProject.layout.buildDirectory)
}

3.4.2 模块级 build.gradle.kts

// 模块级 build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

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

    defaultConfig {
        applicationId = "com.example.workmanagerdemo"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    // AndroidX 核心库
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")

    // WorkManager (集成协程扩展)
    implementation("androidx.work:work-runtime-ktx:2.9.0")

    // Kotlin 协程
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    // 协程核心库 (通常由 android 库传递依赖, 显式声明用于版本锁定)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")

    // 生命周期 (可选, 用于协程感知的 LifecycleScope)
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")

    // 测试依赖
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.5")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

3.5 常见配置错误与解决方案

环境搭建阶段最常遇到以下四类问题，请对照排查：

./gradlew wrapper --gradle-version=8.5

configurations.all {
    resolutionStrategy {
        force("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
        force("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    }
}

org.gradle.caching=true
org.gradle.configuration-cache=true
kotlin.code.style=official
android.useAndroidX=true

3.6 验证环境配置

完成上述配置后，在终端执行以下命令验证环境是否就绪：

# 检查 JDK 版本
java --version

# 检查 Gradle 版本
./gradlew --version

# 检查依赖是否正常解析
./gradlew :app:dependencies --configuration implementation

若终端输出中无红色 Error 信息，且 :app:dependencies 结果中包含 androidx.work:work-runtime-ktx:2.9.0 与 org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3，则环境搭建成功。