Hilt 与 Kotlin 版本不兼容导致编译失败

Question

在使用 Hilt 进行依赖注入时，常因 Hilt 版本与 Kotlin 编译器版本不兼容导致编译失败。典型表现为：AGP 构建时报错“Could not find compatible versions for kotlin and hilt-android-compiler”，或出现“Symbol is declared in module which does not export package”。其根本原因在于 Hilt 依赖的 Kotlin 插件版本有明确范围限制。例如，Hilt 2.48 及以下版本不支持 Kotlin 1.9+，需升级至 Hilt 2.49+ 才能兼容。此外，Kotlin Gradle Plugin、Hilt Gradle Plugin 与 Android Gradle Plugin 三者版本也需协同适配。解决方法是查阅官方兼容性矩阵，统一更新依赖版本，并确保 project 级与 module 级 build.gradle 中配置一致，避免混合使用不匹配的版本导致构建中断。

Answer 1

深入解析 Hilt 与 Kotlin 编译器版本兼容性问题及构建解决方案

1. 问题背景：Hilt 版本与 Kotlin 编译器不兼容的典型表现

在使用 Hilt 进行依赖注入时，开发者常遇到编译失败的问题。最常见的报错信息包括：

• Could not find compatible versions for kotlin and hilt-android-compiler
• Symbol is declared in module which does not export package
• Hilt processor threw an exception: java.lang.NoSuchMethodError

这些错误通常出现在 AGP（Android Gradle Plugin）构建阶段，尤其是在升级 Kotlin 或 AGP 后突然出现。

2. 根本原因分析：Hilt 对 Kotlin 插件的版本约束

Hilt 的底层基于 Dagger 和 annotation processing，其注解处理器（hilt-android-compiler）对 Kotlin 编译器有严格的版本依赖。例如：

Hilt 版本	支持的 Kotlin 版本	是否支持 Kotlin 1.9+
2.44 - 2.48	1.7.20 - 1.8.20	❌ 不支持
2.49	1.8.20 - 1.9.10	✅ 支持
2.50+	1.9.10 - 2.0.0	✅ 支持

如上表所示，若项目使用 Kotlin 1.9.20 但 Hilt 版本仍为 2.48，则会因编译器 API 变更导致符号无法导出或处理失败。

3. 深层机制：为何会出现 "module does not export package" 错误？

该错误源于 JVM 模块系统（JPMS）中模块路径（module path）的访问控制。Kotlin 1.9 引入了更严格的模块封装策略，而旧版 Hilt 编译器未正确声明模块导出规则。具体流程如下：

// 示例：Hilt 注解处理器尝试访问内部类
@AndroidEntryPoint
class MainActivity : AppCompatActivity() {
    @Inject lateinit var userManager: UserManager
}
    

当 hilt-android-compiler 尝试生成 MainActivity_HiltComponents 时，若其运行在不兼容的 Kotlin 环境下，会因无法访问 kotlin.reflect 或 dagger.spi 中的包而抛出访问异常。

4. 多维度依赖协同：AGP、KGP 与 Hilt 的三角关系

除了 Hilt 与 Kotlin 的匹配外，还需考虑三者之间的版本协同：

Android Gradle Plugin	Kotlin Gradle Plugin	Hilt Gradle Plugin	推荐组合
7.4.x	1.8.10	2.48	稳定组合
8.0.x	1.9.10	2.49	兼容升级
8.1.x	1.9.20	2.50	生产推荐
8.2.x	2.0.0	2.51	最新适配

若 project 级 build.gradle 使用 AGP 8.1 而 module 级仍引用 Hilt 2.48，则即使 Kotlin 版本正确也会触发构建冲突。

5. 解决方案实施路径

遵循以下步骤可系统性解决版本不兼容问题：

1. 检查当前 Kotlin 版本：./gradlew kotlinVersion
2. 查阅 Dagger 官方兼容性矩阵
3. 统一 project 与 module 的插件版本声明
4. 更新 plugins {} 块中的 Hilt 插件版本
5. 清理并重建项目：./gradlew clean build --refresh-dependencies

6. 实际配置示例

以下是经过验证的 build.gradle.kts 配置片段：

// Project-level build.gradle.kts
plugins {
    val agpVersion = "8.1.2"
    val kotlinVersion = "1.9.20"
    val hiltVersion = "2.50"

    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.hilt) apply false
}

// Module-level build.gradle.kts
plugins {
    id("com.android.application")
    kotlin("android")
    kotlin("kapt")
    id("dagger.hilt.android.plugin")
}

android {
    compileSdk = 34
    // ...
}

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

7. 自动化检测与预防机制

为避免未来再次发生类似问题，建议引入自动化校验脚本。以下为 Gradle 钩子示例：

afterEvaluate {
    tasks.withType {
        options.compilerArgs.add("-Xlint:deprecation")
        doFirst {
            check(HiltVersion.isCompatibleWith(KotlinVersion)) {
                "Hilt $HiltVersion 不兼容 Kotlin $KotlinVersion，请参考官方兼容性矩阵升级"
            }
        }
    }
}
    

8. 架构级思考：依赖管理的最佳实践

对于拥有多个模块的大型项目，推荐采用版本目录（Version Catalog）进行集中管理：

# gradle/libs.versions.toml
[versions]
agp = "8.1.2"
kotlin = "1.9.20"
hilt = "2.50"

[plugins]
hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
    

通过这种方式，所有模块共享同一套依赖基准，极大降低版本漂移风险。

9. 故障排查流程图

graph TD
            A[构建失败] --> B{错误包含 'kotlin' 或 'hilt'?}
            B -->|是| C[检查 Kotlin 与 Hilt 版本]
            B -->|否| D[检查其他依赖冲突]
            C --> E[查阅官方兼容性矩阵]
            E --> F[更新 Hilt 至 2.49+]
            F --> G[同步 AGP 与 KGP 版本]
            G --> H[执行 clean build]
            H --> I[成功构建?]
            I -->|是| J[问题解决]
            I -->|否| K[启用 --stacktrace 分析]

10. 高级场景：跨团队协作中的版本治理

在企业级开发中，建议建立“依赖白名单”制度。通过 CI 流水线强制校验：

• 禁止直接在 module 中声明版本号
• 所有依赖必须通过 central catalog 引入
• PR 合并前自动运行 ./gradlew dependencies 快照比对
• 设置 SonarQube 规则拦截不兼容组合

这种架构治理方式可将 Hilt/Kotlin 兼容性问题从“救火式处理”转变为“防御性设计”。