第2章 工程环境与依赖配置

Navigation Compose 的所有懒加载功能都建立在正确的版本对齐之上。Kotlin 版本、Jetpack Compose 编译器插件版本和 Gradle 插件版本三者必须严格匹配，否则会出现编译失败、运行时崩溃或编译器内部错误。本章从原理出发，给出完整的依赖配置流程、代码示例和常见错误排查方案。

2.1 版本对齐原理

Jetpack Compose 编译器作为 Kotlin 编译器插件，其内部依赖了特定版本的 Kotlin 编译器 API。每个 Compose 编译器版本只与一个或少数几个 Kotlin 主版本兼容。同时，compose-bom（Bill of Materials）或 compose-kotlin-compatibility-extension 负责协调 Kotlin 插件版本和 Compose 编译器版本。

在引入 Navigation Compose 的懒加载依赖时，必须使用与 BOM 一致的版本，避免手动指定版本导致冲突。

2.2 Gradle 依赖配置流程

1. 在项目级 build.gradle.kts 中声明 Kotlin 插件版本和 Compose 编译器版本。
2. 在模块级 build.gradle.kts 中启用 Compose 编译器插件，并通过 composeOptions 指定编译器版本。
3. 添加 Navigation Compose 依赖，推荐使用 BOM 统一管理。

项目级 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("org.jetbrains.kotlin.plugin.compose") version "1.9.22" apply false
}

模块级 build.gradle.kts（示例）

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("org.jetbrains.kotlin.plugin.compose")
}

android {
    namespace = "com.example.navigationlazy"
    compileSdk = 34
    defaultConfig {
        minSdk = 26
        targetSdk = 34
    }
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.14"
    }
}

dependencies {
    val composeBom = platform("androidx.compose:compose-bom:2024.02.00")
    implementation(composeBom)
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.navigation:navigation-compose:2.7.7")
    // Debug 工具
    debugImplementation("androidx.compose.ui:ui-tooling")
    debugImplementation("androidx.compose.ui:ui-test-manifest")
}

2.3 启用 Compose 编译器

从 Kotlin 2.0 开始，推荐使用 org.jetbrains.kotlin.plugin.compose 插件代替 composeOptions 配置。该插件的版本必须与 Kotlin 版本保持完全一致。

如果项目仍使用旧方式，在 android { composeOptions { kotlinCompilerExtensionVersion } } 中指定的编译器版本必须与 compose-compiler 的 Maven 坐标匹配。新版插件则在插件块中声明即可：

plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.0.10"
}

2.4 常见错误与调试

• 错误：This version of the Compose compiler requires Kotlin version X.X.X but you are using Y.Y.Y
  解决：对照版本兼容表（见2.1节表格），升级或降级 Kotlin。
• 错误：Plugin 'kotlin-android' was applied but the Kotlin compiler extension for Compose is missing
  解决：添加 id("org.jetbrains.kotlin.plugin.compose") 插件。
• 错误：e: java.lang.NoSuchFieldError: some class
  解决：清理缓存并重新同步 Gradle；检查是否有多个 Compose 依赖版本不一致。
• 调试技巧：在终端运行 ./gradlew dependencies --configuration runtimeClasspath 查看所有 Compose 相关依赖的版本树，快速定位冲突。

2.5 版本对齐流程示意图

下图展示了从 Gradle 插件声明到 Compose 编译器启用的完整版本对齐流程：

以上为第2章全部内容。完成版本对齐后，即可进入第3章：Navigation Compose 路由懒加载基础原理。