运行Android项目时遇Hilt不支持元数据版本错误求助

问题详情 #

运行Android项目时触发Hilt编译错误，环境为Android Studio Jellyfish，Hilt版本2.51.1，报错信息如下：

error: [Hilt]
  Unsupported metadata version. Check that your Kotlin version is >= 1.0: java.lang.IllegalStateException: Unsupported metadata version. Check that your Kotlin version is >= 1.0
    at dagger.hilt.processor.internal.kotlin.KotlinMetadata.metadataOf(KotlinMetadata.java:200)
    at dagger.hilt.processor.internal.kotlin.KotlinMetadata.from(KotlinMetadata.java:182)
    at java.base/java.util.HashMap.computeIfAbsent(Unknown Source)

  [Hilt] Processing did not complete. See error above for details.
1 error

app模块Gradle配置：

import com.android.build.gradle.internal.utils.isKotlinKaptPluginApplied

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.jetbrains.kotlin.android)
    id("kotlin-kapt")
    id("com.google.dagger.hilt.android")
}

dependencies {

    //Dagger - Hilt
    implementation("com.google.dagger:hilt-android:2.51.1")
    kapt ("com.google.dagger:hilt-compiler:2.51.1")
    implementation ("androidx.hilt:hilt-lifecycle-viewmodel:1.0.0-alpha03")
    kapt ("androidx.hilt:hilt-compiler:1.0.0")
    implementation ("androidx.hilt:hilt-navigation-compose:1.0.0-alpha03")
}
kapt {
    correctErrorTypes=true
}

解决步骤 #

这个错误本质是Kotlin版本与Hilt版本不兼容，同时你的AndroidX Hilt依赖版本混乱，按以下步骤修复：

1. 确认Kotlin版本
   打开项目根目录的libs.versions.toml文件，找到jetbrains.kotlin.android对应的版本号。Android Studio Jellyfish默认搭载的Kotlin版本通常是1.10.x或更高，而Hilt 2.51.1只支持到Kotlin 1.9.x，这是核心冲突点。

2. 升级Hilt版本到兼容Kotlin的版本
   如果你的Kotlin是1.10.x+，把Hilt核心版本升级到2.52及以上（比如2.52.1），同时同步更新所有AndroidX Hilt依赖到稳定版：
   修改app模块Gradle的依赖部分：

   // Dagger - Hilt
   implementation("com.google.dagger:hilt-android:2.52.1")
   kapt("com.google.dagger:hilt-compiler:2.52.1")
   // AndroidX Hilt 统一用稳定版
   implementation("androidx.hilt:hilt-lifecycle-viewmodel:1.1.0")
   implementation("androidx.hilt:hilt-navigation-compose:1.1.0")
   kapt("androidx.hilt:hilt-compiler:1.1.0")
   

3. 清理并重建项目
   执行Build -> Clean Project，然后Build -> Rebuild Project，最后同步Gradle。

补充说明 #

• 永远保持Hilt核心依赖与编译器版本一致，AndroidX Hilt的版本也要和核心Hilt版本匹配（比如Hilt 2.52+对应AndroidX Hilt 1.1.0+）
• 避免使用alpha版本的AndroidX Hilt依赖，优先选择稳定版减少兼容性问题

内容的提问来源于stack exchange，提问作者Sanchay Saxena