Dagger Hilt 在 Android 项目中的正确配置指南

在 Android 开发中使用 Dagger Hilt 进行依赖注入时，经常会遇到各种配置问题。本文将详细介绍如何正确配置 Dagger Hilt，避免常见的编译错误。

常见配置错误分析

开发者在配置 Dagger Hilt 时最常遇到的错误之一是 Expected @AndroidEntryPoint to have a value。这个错误通常表明 Hilt Gradle 插件没有被正确应用。错误信息会提示开发者检查是否忘记了应用 Gradle 插件。

项目级配置要点

在项目的顶级 build.gradle.kts 文件中，需要确保以下配置：

1. 添加 Hilt 的 classpath 依赖
2. 声明 KSP 插件版本
3. 正确设置插件应用范围

buildscript {
    dependencies {
        classpath("com.google.dagger:hilt-android-gradle-plugin:2.48.1")
    }
}

plugins {
    id("com.google.devtools.ksp") version "1.9.21-1.0.15" apply false
}

模块级配置关键

在模块级的 build.gradle.kts 文件中，配置更为关键：

1. 应用 Hilt 插件时不应使用 apply false
2. KSP 插件只需应用，不需指定版本
3. 确保 kapt 配置正确

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

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

kapt {
    correctErrorTypes = true
}

常见问题解决方案

1. KSP 插件冲突问题：当出现 "The KSP plugin was detected to be applied but its task class could not be found" 错误时，需要在项目级声明 KSP 版本，在模块级只应用插件而不指定版本。

2. Hilt 注解处理器问题：确保使用 kapt 而不是 annotationProcessor 来处理 Hilt 注解。

3. 类型擦除问题：通过 kapt 配置中的 correctErrorTypes = true 来解决 Hilt 生成的代码类型问题。

最佳实践建议

1. 保持 Dagger Hilt 版本与其他相关库版本同步更新
2. 在模块级 build 文件中只应用插件，版本统一在项目级管理
3. 使用 Kotlin DSL 时注意插件应用的语法差异
4. 清理构建缓存后重新构建可以解决许多配置更新后的问题

通过遵循这些配置原则，可以避免大多数 Dagger Hilt 在 Android 项目中的集成问题，确保依赖注入系统正常工作。