Hilt 中使用 KSP 替代 KAPT

问题描述

在 Android 开发中配置 Hilt 依赖注入框架时，许多开发者希望用 Kotlin Symbol Processing (KSP) 替代过时的 KAPT（Kotlin Annotation Processing Tool）。常见的问题症状包括：

• 版本冲突导致的构建失败
• 混淆的依赖关系配置
• 与 Compose 或 Kotlin 版本不兼容
• 尝试不同版本组合后仍无法工作

核心问题源于Kotlin、KSP、Hilt 和 Jetpack Compose 的版本必须严格兼容。配置错误时会出现各种未明确定义的构建错误。

版本兼容性原理

解决该问题前，需理解各组件的依赖关系：

1. KSP 版本格式：如 1.9.23-1.0.20

   • 前半部分（1.9.23）必须匹配 Kotlin 版本
   • 后半部分（1.0.20）为 KSP 自身版本

2. Kotlin 与 Compose
   版本映射关系详见官方兼容性文档

3. Hilt 与 KSP
   Hilt 从 2.48 版本开始支持 KSP，详情见Dagger KSP 文档

关键原则

Kotlin ≥ 2.0.0 时需使用 org.jetbrains.kotlin.plugin.compose 插件，不再需要 kotlinCompilerExtensionVersion

解决方案

Kotlin < 2.0.0 配置（如 1.9.x）

项目级 build.gradle.kts

plugins {
    // 保持版本一致！
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
    id("com.google.dagger.hilt.android") version "2.51" apply false
    id("com.google.devtools.ksp") version "1.9.0-1.0.13" apply false
}

模块级 build.gradle.kts

plugins {
    id("org.jetbrains.kotlin.android")
    id("com.google.dagger.hilt.android")
    id("com.google.devtools.ksp")
}

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.2"  // 匹配 Kotlin 1.9.0
    }
}

dependencies {
    val hiltVersion = "2.51"
    implementation("com.google.dagger:hilt-android:$hiltVersion")
    ksp("com.google.dagger:hilt-compiler:$hiltVersion")
}

Kotlin ≥ 2.0.0 配置（如 2.0.21）

项目级 build.gradle.kts

plugins {
    // 版本必须严格匹配！
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
    kotlin("plugin.compose") version "2.0.21" apply false  // 新增插件
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
    id("com.google.devtools.ksp") version "2.0.21-1.0.28" apply false
}

模块级 build.gradle.kts

plugins {
    id("org.jetbrains.kotlin.android")
    kotlin("plugin.compose")  // 应用新插件
    id("com.google.dagger.hilt.android")
    id("com.google.devtools.ksp")
}

// 移除 kotlinCompilerExtensionVersion！

dependencies {
    implementation("com.google.dagger:hilt-android:2.51.1")
    ksp("com.google.dagger:hilt-compiler:2.51.1")
}

使用 Version Catalog（推荐）

在 gradle/libs.versions.toml 中统一管理版本：

[versions]
kotlin = "2.0.21"
ksp = "2.0.21-1.0.28"  # 前半部分匹配 Kotlin 版本
hilt = "2.51.1"

[libraries]
dagger-hilt = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
dagger-hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
hilt-android = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

模块级 build.gradle.kts 使用：

plugins {
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    alias(libs.plugins.hilt.android)
    alias(libs.plugins.ksp)
}

dependencies {
    implementation(libs.dagger.hilt)
    ksp(libs.dagger.hilt.compiler)
}

版本兼容验证步骤

1. 确认项目级与模块级 Kotlin 版本一致
2. 检查 KSP 版本格式：<Kotlin_version>-<Ksp_version>
3. Kotlin ≥ 2.0.0 时添加 kotlin.plugin.compose
4. 移除所有重复或冲突的依赖声明

调试技巧

遇到构建失败时：

1. 运行 ./gradlew cleanBuildCache
2. 检查 kspDebugKotlin 任务日志
3. 在 KSP Release 页面 验证版本兼容
4. 临时添加日志诊断：

   tasks.withType<com.google.devtools.ksp.gradle.KspTask> {
         it.logLevel = LogLevel.INFO
   }

最佳实践

1. 单一版本源
   使用 libs.versions.toml 统一管理所有版本号

2. 逐步升级
   Kotlin → Compose (验证兼容表) → KSP → Hilt

3. 关键检查点：

   println("Kotlin: ${KotlinVersion.CURRENT}")
   println("KSP: ${com.google.devtools.ksp.Version.KSP_VERSION}")

典型错误

• 同时声明 kapt 和 ksp
• Kotlin版本在项目/模块级配置不一致
• 使用过时的 Hilt 依赖写法（如 hilt-android-compiler)

通过严格遵守版本兼容规则和集中管理依赖，可确保 Hilt 与 KSP 高效协作，显著提升构建速度与开发体验。