第3章：依赖缺失——连门都没进，就谈什么编译

相信我，这一章我敢打赌——你遇到过的 Hilt 编译报错里，有一大半都跟这章讲的问题有关。

说白了就是：你辛辛苦苦写好了 @HiltAndroidApp、@AndroidEntryPoint，满怀期待地点击 Build，结果 Gradle 直接甩你一脸看不懂的红色日志。什么 Dagger、Hilt、unsupported……一开始我以为是代码写错了，研究了半天才发现——嗯，连 Hilt 的依赖都没加全。

所以，咱们先把地基打牢。

3.1 依赖缺失的两大坑

Hilt 的依赖，不像有些人想的“加一个库就完事”。它分三层：

• 项目级 Gralde 插件——告诉 Android 构建系统我要用 Hilt
• 模块级 implementation 依赖——引入 Hilt 的核心库
• 注解处理器/编译器插件——KAPT 或 KSP，这是生成代码的关键

任何一个漏掉，Hilt 就像断了电的机器——动不了。

3.2 KAPT vs KSP：选哪个？

我最早做 Hilt 项目的时候用的是 KAPT，那时候 KSP 还没那么普及。后来到了 2.44 版本之后，Hilt 开始正式支持 KSP。两者的区别，我整理了个表格：

我个人习惯：新项目用 KSP，旧项目如果已经稳定运行 KAPT 就别折腾了。但不管用哪个，插件和编译器依赖一个都不能少。

3.3 完整配置清单（Gradle 7.x + AGP 8.x）

咱们直接来个标准模版。假设你用的是 Kotlin + KAPT：

项目级 build.gradle

buildscript {
    dependencies {
        classpath "com.google.dagger:hilt-android-gradle-plugin:2.48"
        // 如果你用 KSP：
        // classpath "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin:1.9.0-1.0.13"
    }
}

模块级 build.gradle

apply plugin: 'kotlin-kapt'
apply plugin: 'dagger.hilt.android.plugin'

android {
    // 常规配置...
}

dependencies {
    implementation "com.google.dagger:hilt-android:2.48"
    kapt "com.google.dagger:hilt-compiler:2.48"
    
    // 如果需要 ViewModel 支持：
    implementation "androidx.hilt:hilt-navigation-compose:1.1.0"
    // 或者传统 Fragment：
    implementation "androidx.hilt:hilt-work:1.1.0"
    
    // 如果是 KSP 版本：
    // ksp "com.google.dagger:hilt-compiler:2.48"
}

3.4 别忽略 Kotlin 插件顺序

还有一个不起眼但致命的问题：插件的加载顺序。

在模块级的 build.gradle 顶部，你写了：

apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-kapt'
apply plugin: 'dagger.hilt.android.plugin'

顺序很重要！kotlin-kapt 必须在 Hilt 插件之前加载。如果反了，Gradle 会报类似 Plugin with id 'dagger.hilt.android.plugin' not found 的错误——这种错最坑，因为它暗示你没加插件，实际上你加了，只是顺序不对。

3.5 你可能会遇到的那些报错

我整理了 3 个最高频的、跟依赖缺失相关的错误信息，你大概率也见过：

1. Execution failed for task ':app:kaptGenerateStubsDebugKotlin'.

   ▶ 原因：Hilt 注解处理器未找到，或者 KAPT 插件未配置。检查 kotlin-kapt 插件和 hilt-compiler 依赖。

2. Cannot find symbol class Hilt_App

   ▶ 原因：Hilt 未生成所需的依赖注入基类。通常是因为漏了 apply plugin: 'dagger.hilt.android.plugin'。

3. Unresolved reference: HiltAndroidApp

   ▶ 原因：hilt-android 核心库的 implementation 依赖未添加，或者版本号与编译器不一致。

遇到这些错误，别慌。先按上面的配置清单一行一行核对，八成能解决。

3.6 一张图搞定依赖关系

为了让你更直观地理解 Hilt 在 Gradle 构建链路中的位置，我画了张图：

3.7 避坑指南：防患于未然

最后，我分享三个我实际踩过的坑，帮你避免浪费时间：

• 我曾经把 KAPT 和 KSP 同时加在同一个模块里，结果 Gradle 不知道用哪个处理器，直接炸了。记住了：一个模块只选一种处理器方式。
• 升级 AGP 后忘记同时升级 KAPT 版本。Kotlin 1.8 对应 KAPT 1.8，Kotlin 1.9 对应 KAPT 1.9。版本不匹配，编译时会出现 incompatible 的警告甚至错误。
• 多模块项目中，只在主 app 模块加了 hilt-compiler，结果其他 feature 模块里用到 Hilt 注解时全部报红。正确的做法是：每个需要 Hilt 的模块都要加 hilt-compiler（或 ksp）。