在 Android Studio 的 libs.versions.toml 文件中配置 Hilt 依赖

问题描述

当在 Android Studio 的项目中使用 libs.versions.toml 文件（版本目录）添加 Hilt 依赖时，经常会出现依赖无法识别或项目同步错误的情况。具体表现为：

典型错误

在 build.gradle.kts 文件中尝试添加 implementation(libs.hilt) 时会显示报错："Unresolved reference: hilt"

该问题的主要原因是：

1. TOML 文件中 Hilt 依赖的声明不正确或命名不规范
2. 项目与模块级别的 Gradle 文件配置缺失关键步骤
3. 未正确配置 KSP（Kotlin 符号处理）插件进行代码生成

以下是完整的解决方案，适用于 Android Studio Iguana 及以上版本。

完整解决方案

步骤一：配置 libs.versions.toml 文件

在项目根目录下的 gradle/libs.versions.toml 文件中添加以下内容：

[versions]
hilt = "2.48.1"    # 请替换为最新版本
ksp = "1.9.20-1.0.14" # KSP 版本应匹配 Kotlin 版本

[libraries]
# Hilt 主依赖
hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
# Hilt 编译器（通过 KSP 处理）
hilt-compiler = { group = "com.google.dagger", name = "hilt-compiler", version.ref = "hilt" }

[plugins]
# Hilt Android 插件
hilt-android = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
# Kotlin 符号处理插件
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

版本提示

请从以下官方源获取最新版本号：

• Hilt 最新版本
• KSP 最新版本

步骤二：配置项目级 build.gradle.kts

在项目根目录的 build.gradle.kts 中添加插件引用：

plugins {
    // 其他插件...
    alias(libs.plugins.hilt.android) apply false
    alias(libs.plugins.ksp) apply false
}

步骤三：配置应用级 build.gradle.kts

在 app 模块的 build.gradle.kts 文件中：

plugins {
    alias(libs.plugins.androidApplication)
    alias(libs.plugins.kotlinAndroid)
    // 添加 Hilt 和 KSP 插件
    alias(libs.plugins.hilt.android)
    alias(libs.plugins.ksp)
}

dependencies {
    // Hilt 主依赖
    implementation(libs.hilt.android)
    // Hilt 编译器 (KSP 替代 kapt)
    ksp(libs.hilt.compiler)
}

步骤四：同步与构建项目

1. 点击 Sync Project with Gradle Files 按钮
2. 同步完成后执行 Build > Clean Project
3. 重新构建项目 Build > Rebuild Project

KSP vs KAPT

Kotlin 项目中推荐使用 KSP 代替 KAPT：

• 编译速度更快
• 对 Kotlin 扩展功能支持更好
• 专为 Kotlin 符号处理设计

故障排除

若问题仍未解决，请检查：

1. TOML 命名一致性：确保 build.gradle.kts 中引用的名称与 TOML 中 [libraries] 部分的名称一致

   // 正确：引用 hilt-android
   implementation(libs.hilt.android) 
   
   // 错误：libs.hilt 不存在
   implementation(libs.hilt)

2. 依赖项冲突：确保所有 Hilt 相关依赖使用相同版本号

   # 确保所有 .ref 指向同一个版本标识
   [versions]
   hilt = "2.48.1"
   
   [libraries]
   hilt-android = { ... version.ref = "hilt" }

3. 插件加载顺序：Hilt 插件应声明在 Android 应用插件之后

4. 缓存问题：执行以下操作清除缓存：

   • File > Invalidate Caches / Restart
   • 删除 .gradle 缓存目录

备选方案：使用 KAPT

如果仍需使用 KAPT 进行依赖注入器生成，可修改配置如下：

// app/build.gradle.kts
dependencies {
    implementation(libs.hilt.android)
    kapt(libs.hilt.compiler)  // 使用 kapt 替代 ksp
}

# libs.versions.toml
[libraries]
# 无需 KSP 库的声明

注意事项

使用 KAPT 时：

1. 确保应用了 Kotlin KAPT 插件：kotlin("kapt")
2. 编译速度可能显著慢于 KSP 解决方案

按照上述步骤配置后，Hilt 依赖项应能正确解析并解决原始问题中的错误提示。此方案适用于新的 Gradle 版本目录系统，能有效管理依赖版本并保持项目配置的可维护性。