📚 课程目录第3章 Hilt项目配置

Hilt 项目配置：添加依赖、初始化 Application、@HiltAndroidApp

配置 Hilt 的第一步，就是把它请进项目。说实话，这一步看着简单，但踩坑的人不少。我刚开始用 Hilt 时，图省事直接从网上复制了一段依赖配置，结果编译就报了一堆错。

后来才明白，版本号、构建插件、包名声明，一个都不能乱。下面我把每一步拆开讲，你跟着做就不会有问题。

1. 添加依赖：从项目级到模块级

Hilt 需要两处配置：项目根目录的 build.gradle（或 build.gradle.kts），以及 app 模块的 build.gradle。

📍 项目级（root build.gradle）——添加 Hilt Gradle 插件。

// build.gradle (Project级别)
buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.google.dagger:hilt-android-gradle-plugin:2.48" // 版本号建议与Hilt核心库对齐
    }
}

📍 模块级（app/build.gradle）——应用插件 + 添加依赖。

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'dagger.hilt.android.plugin'
}

android {
    // ... 其他配置
}

dependencies {
    implementation "com.google.dagger:hilt-android:2.48"
    kapt "com.google.dagger:hilt-android-compiler:2.48"

    // 如果你用 Kotlin 1.7+，建议用 ksp 替代 kapt 以提升编译速度
    // ksp "com.google.dagger:hilt-android-compiler:2.48"
}

嗯，这里有个细节：kapt 和 ksp 的选择。我个人的经验是，如果项目 Kotlin 版本较低（1.6 左右），老老实实用 kapt；如果你已经升级到 1.8+ 而且用了 ksp 插件，那就切到 ksp。我在一个老项目里试过强制升 ksp，结果 Room 也报错，后来统一降回 kapt 才稳住。

⚠️ 版本兼容雷区
Hilt 2.48 要求 AGP ≥ 7.2、Kotlin ≥ 1.6。不同版本对应关系如下：

Hilt 版本	最小 AGP	最小 Kotlin	推荐 kapt/ksp
2.44	7.0	1.5	kapt
2.46	7.2	1.6	kapt 或 ksp
2.48	7.2	1.6	kapt 或 ksp
2.50+	8.0	1.8	ksp 优先

💡 小技巧
配置完记得触发一次 Gradle Sync。如果同步成功，插件就会自动注册一个 hilt 任务组，你可以用 ./gradlew tasks | grep hilt 验证。

2. 初始化 Application：@HiltAndroidApp

依赖加好了，插件也应用了，但 Hilt 还不知道你的应用入口是谁。你需要给它一个「总开关」——@HiltAndroidApp 注解。

找到你的 Application 类（如果没有，创建一个），加上这个注解：

import dagger.hilt.android.HiltAndroidApp

@HiltAndroidApp
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        // 你可以在这里初始化其他库，但不要调用 Hilt 相关API
    }
}

就这么简单？对，就这么简单。这个注解会让 Hilt 在编译时生成一个 Hilt_MyApp 基类，它自动处理了 ComponentManager 的初始化和生命周期。说白了，它就是 Hilt 的「总电源插头」。

我曾经接手过一个项目，队友加了 @HiltAndroidApp 但忘记在 AndroidManifest.xml 里把 android:name 指向这个类，结果 Hilt 完全没生效，所有注入都是 null。后来定位了半天才发现是这个低级错误。

✅ 请确认 AndroidManifest.xml 中的 Application 配置：

<application
    android:name=".MyApp"
    android:label="@string/app_name"
    ... >
    <!-- 其他 Activity / 组件 -->
</application>

3. 常见配置陷阱：我踩过的几个坑

Kotlin 版本不匹配： Hilt 2.44 之后对 Kotlin 版本有硬性要求。如果 Kotlin 版本低于 1.6，编译会直接报 Unsupported class file major version。我记得有一次升级 Kotlin 到 1.9，但 Hilt 没跟上，只好降回 2.46 才编译通过。
插件顺序： 在 plugins 块中，dagger.hilt.android.plugin 要放在 kotlin-android 后面。某些 Gradle 版本会把顺序冲突提示为「缺少 kotlin 插件」，挺误导人的。
kapt 与 Java 17： 如果你用 JDK 17，kapt 可能会有 Error: warnings found and -Werror specified。我当时的解决办法是去掉 allWarningsAsErrors，或者改用 ksp。
Multi-module 项目： 每个需要注入的模块都要在根目录的 build.gradle 中应用相同的 Hilt 插件，否则注入会失败。

⚠️ 我曾经遇到的一个最诡异的 Bug：
项目所有依赖都配好了，@HiltAndroidApp 也加了，但运行到 onCreate 就闪退，报错 Dagger does not know how to create this instance。查了一天发现是混淆规则把 Hilt 的代码给压缩掉了。解决方案是在 proguard-rules.pro 里加上：

-keep class dagger.hilt.** { *; }
-keep class javax.inject.** { *; }

4. 验证配置是否成功

配置完成后，别急着写注入代码。先做个快速验证：

编译项目，确认没有红色报错。
在任意 Activity 里临时加一行 @Inject lateinit var someString: String（不构建实际 Module）——如果能编译通过，说明 Hilt 已经启用。
运行 App，用 adb logcat | grep "Hilt" 过滤日志，应该能看到类似 Hilt Android Application: [Dagger] Hilt_MyApp created 的输出。

还记得我刚才说的吗？验证这一步我用 @Inject 加一个 String 只是为了看编译是否触发注解处理器。如果没配置 kapt/ksp，编译器根本不会报错，那就要回头看依赖配置了。

上图就是 Hilt 项目配置的完整链条，你可以对照着一步一步走。别急，哪怕第一次配置花个十分钟，也比后面定位注入失败省时间。

💡 我常用的快速脚手架方法：
新建一个 Demo 项目，按上述步骤配好 Hilt，然后跑一个最简单的 @Inject 测试。如果 Demo 通了，再把这个配置照搬到真实项目中。这样能隔离掉项目自身的问题。

配置阶段到这里就结束了。接下来，你就能用 @Inject、@Module 等注解去创建依赖图了——不过那是第4章的内容。现在先把环境搭牢，别留隐患。