第1章 Hilt构建失败：缺少@HiltAndroidApp注解

刚接触 Hilt 的时候，我印象最深的一次报错就是项目死活编译不过去。控制台刷了一堆红字，翻来覆去就一句话——@HiltAndroidApp 没找到。怎么说呢，当时我盯着 Application 类看了十分钟，愣是没反应过来。

其实这个错误特别常见，尤其是从 Dagger 2 手动搭迁移过来的团队。Hilt 作为 Dagger 的上层封装，做了很多自动化的工作，但前提是你得给个「入口」。这个入口就是 @HiltAndroidApp。

1.1 问题现象

来看看典型的报错信息（Gradle 构建输出）：

error: [Hilt] @HiltAndroidApp is required on the base Application class to use Hilt.
        com.example.myapp.MyApplication

或者更隐晦一点：

error: No annotation processor found for Hilt. Did you forget to apply the Hilt Gradle plugin?

嗯，第二种情况容易让人误会是插件没配。实际上，插件配好了，但没有 @HiltAndroidApp，依然报同样的错。

1.2 根因分析

Hilt 的依赖注入流程，说白了就是「你告诉它从哪开始，它帮你自动生成所有 Dagger 组件」。@HiltAndroidApp 就是那个「开始」的标记。

具体来说，Hilt 编译器会扫描所有 @HiltAndroidApp 注解的类，然后：

• 生成一个基类 Hilt_MyApplication（继承自你的 Application）
• 自动创建 Dagger 的 SingletonComponent 和 ActivityComponent 等组件
• 在 AndroidManifest.xml 中注册的 MyApplication 会被 Hilt 替换成 Hilt_MyApplication（通过字节码插桩）

没有这个注解，上面的步骤全部跳过。你的项目里虽然引入了 Hilt 的依赖，但编译器不知道从哪生成代码，自然就报错了。

1.3 解决方案

修复方法非常简单，三步走：

1. 在 build.gradle（Module 级别）中应用 Hilt 插件：

plugins {
    id 'com.android.application'
    id 'dagger.hilt.android.plugin'  // 别忘了这个
}

2. 添加依赖（确保 hilt-android-compiler 使用 kapt 或 ksp 处理）：

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

3. 修改你的 Application 类：

@HiltAndroidApp
class MyApplication : Application() {
    // 无需额外代码
}

改完之后重新构建，记得先 clean 再 rebuild。Hilt 的注解处理器会在编译阶段生成代码，有时增量编译会导致残留的 .class 文件干扰。

1.4 避坑指南

分享了几个我踩过的坑：

• 插件版本和依赖版本不匹配。 Hilt 的主版本号（比如 2.50）需要保持一致，我见过有人 plugin 用 2.48，implementation 用 2.50，结果构建失败。
• Kotlin 版本太低。 Hilt 2.50 要求 Kotlin 1.9+，如果项目还在用 1.6，会报一些奇怪的编译错误。
• 多 Module 项目。 如果有一个 lib module 也想用 Hilt，不需要 @HiltAndroidApp，但需要加上 @HiltViewModel 这类注解。Application 级注解必须在主 app module。

我曾经在一个遗留项目里导入 Hilt，结果因为 Application 类所在的包名改了，但 @HiltAndroidApp 忘了更新，折腾了半天才定位到。所以建议写个单元测试或者 CI 脚本，在编译阶段检查 Application 类上是否标注了该注解。

1.5 核心流程图

下面这张图展示了缺少 @HiltAndroidApp 时，Hilt 的初始化链路在哪里断裂：

1.6 总结要点

• 一注解定乾坤： @HiltAndroidApp 是 Hilt 的入口点，缺失则构建失败。
• 检查顺序： 先看 gradle 插件是否应用，再看 Application 类是否标注，最后检查 manifest。
• clean 是万能钥匙： 遇到奇怪的问题，先 ./gradlew clean 再构建。