Hilt 不支持元数据版本问题

警告

本文提供的信息截至 2024 年 9 月仍然有效。Kotlin 和 Hilt 版本经常更新，请及时查看官方文档获取最新信息。

问题描述

在使用 Kotlin 1.5.10 和 Hilt 依赖注入框架时，开发者遇到以下错误：

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.internal.codegen.kotlin.KotlinMetadata.metadataOf(KotlinMetadata.java:206)

这个错误通常表示 Hilt 使用的 Kotlin 元数据版本与项目中的 Kotlin 版本不兼容。

根本原因

Hilt 依赖注入框架需要与 Kotlin 编译器版本保持兼容。当两者版本不匹配时，就会出现元数据版本不支持的编译错误。

解决方案

方案一：更新到兼容版本组合

根据多数用户反馈，以下版本组合能够解决该问题：

Kotlin DSL - Project

// build.gradle.kts (Project level)
plugins {
    // ... 其他插件
    id("org.jetbrains.kotlin.android") version "1.9.24" apply false
    id("com.google.dagger.hilt.android") version "2.48" apply false
}

Kotlin DSL - App

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

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

// 允许引用生成的代码
kapt {
    correctErrorTypes = true
}

Groovy DSL - Project

// build.gradle (Project level)
buildscript {
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24"
        classpath "com.google.dagger:hilt-android-gradle-plugin:2.48"
    }
}

Groovy DSL - App

// build.gradle (App level)
plugins {
    id 'kotlin-kapt'
    id 'com.google.dagger.hilt.android'
}

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

kapt {
    correctErrorTypes true
}

方案二：使用版本目录（推荐）

对于更复杂的项目，建议使用版本目录管理依赖：

libs.versions.toml

[versions]
kotlin = "1.9.24"
hilt = "2.48"

[libraries]
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }

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

Project Build

// settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml"))
        }
    }
}

App Build

// build.gradle.kts (App level)
plugins {
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.hilt.android)
    kotlin("kapt")
}

dependencies {
    implementation(libs.hilt.android)
    kapt(libs.hilt.compiler)
}

方案三：特定版本对应关系

以下是一些经过验证的 Kotlin 与 Hilt 版本组合：

Kotlin 版本	Hilt 版本	说明
1.5.10+	2.37-2.40	较旧的兼容组合
1.7.0+	2.42-2.44	中间版本组合
1.8.0+	2.44-2.45	推荐稳定组合
1.9.0+	2.48-2.50	最新稳定组合
2.0.0+	2.51.1+	最新实验组合

方案四：检查其他相关依赖

确保所有 Hilt 相关依赖版本一致：

dependencies {
    // 核心 Hilt
    implementation("com.google.dagger:hilt-android:2.48")
    kapt("com.google.dagger:hilt-android-compiler:2.48")
    
    // AndroidX Hilt
    implementation("androidx.hilt:hilt-navigation-compose:1.2.0")
    kapt("androidx.hilt:hilt-compiler:1.0.0")
    
    // 其他相关依赖
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.2")
}

常见错误与解决方法

注意

1. 版本不一致：确保项目级和模块级的 Hilt 版本完全相同
2. Kotlin 版本过旧：更新 Kotlin 版本以支持所需的 Hilt 版本
3. 缺少 kapt 配置：确保启用了 kotlin-kapt 插件并设置了 correctErrorTypes = true

故障排除步骤

如果问题仍然存在，请尝试以下步骤：

1. 清理并重新构建项目：

   ./gradlew clean build

2. 启用详细日志以获取更多信息：

   ./gradlew build --info --stacktrace

3. 检查是否存在其他过时的依赖：

   ./gradlew dependencyUpdates

4. 如果使用 KSP，确保版本兼容：

   plugins {
       id("com.google.devtools.ksp") version "1.9.24-1.0.20"
   }

结论

Hilt 的 "Unsupported metadata version" 错误通常由版本不兼容引起。通过更新到兼容的 Kotlin 和 Hilt 版本组合，并确保所有相关依赖版本一致，可以解决这个问题。

提示

始终参考 Hilt 官方文档 获取最新的版本兼容性信息。

资源推荐

• Hilt 官方文档
• Kotlin 版本发布说明
• Android 开发者文档 - Hilt