2. 项目环境搭建与依赖声明：Gradle配置、Hilt插件、hiltViewModel依赖、版本兼容性

本章将搭建《Hilt与ViewModel集成实践》的完整开发环境。Hilt作为Android官方推荐的依赖注入框架，与ViewModel的集成需要在Gradle构建系统中精确配置插件、依赖项并确保版本兼容性。错误的配置将导致编译失败、运行时错误或注解处理失效，因此本章是后续所有实践章节的基础。

2.1 整体架构流程

下图展示了Hilt与ViewModel集成的完整构建流程，从项目级构建脚本到模块级依赖声明，最终生成支持@HiltViewModel注解的编译产物。

2.2 项目级 Gradle 配置

首先在 项目根目录的 build.gradle.kts（或 build.gradle）中声明 Hilt 插件和 Kotlin/KSP 插件依赖。

// 项目级 build.gradle.kts
plugins {
    id("com.android.application") version "8.4.0" apply false
    id("com.android.library") version "8.4.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.24" apply false
    // Hilt Gradle Plugin
    id("com.google.dagger.hilt.android") version "2.51.1" apply false
    // KSP Plugin（用于 Hilt 编译）
    id("com.google.devtools.ksp") version "1.9.24-1.0.20" apply false
}

// 可选：统一仓库和Java工具链配置
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// Java 工具链统一（推荐）
subprojects {
    tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
        kotlinOptions {
            jvmTarget = "17"
        }
    }
}

2.3 模块级 build.gradle.kts：应用插件与声明依赖

在 app 模块（或应用主模块）的 build.gradle.kts 中，应用上述插件并添加所有与 Hilt、ViewModel 相关的依赖。

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    // Hilt 插件 —— 必须在 Android 插件之后
    id("com.google.dagger.hilt.android")
    // KSP 插件 —— 用于编译时注解处理
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.hiltviewmodelsample"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.hiltviewmodelsample"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }

    // 启用 ViewBinding（可选，用于非Compose集成）
    buildFeatures {
        viewBinding = true
    }
}

dependencies {
    // ========== Hilt 核心 ==========
    implementation("com.google.dagger:hilt-android:2.51.1")
    // Hilt 编译处理器（使用 kapt 或 ksp 二选一）
    kapt("com.google.dagger:hilt-compiler:2.51.1")
    // 如果使用 KSP，则使用以下代替 kapt：
    // ksp("com.google.dagger:hilt-compiler:2.51.1")

    // ========== ViewModel + Hilt 集成 ==========
    // 在 Compose 中使用 @HiltViewModel + hiltViewModel()
    implementation("androidx.hilt:hilt-navigation-compose:1.2.0")
    // ViewModel 核心（生命周期稳定版）
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.4")
    // Saved State Handle 支持
    implementation("androidx.lifecycle:lifecycle-viewmodel-savedstate:2.8.4")

    // ========== Activity/Fragment 集成 ==========
    // 用于非Compose的 @AndroidEntryPoint 支持
    implementation("androidx.activity:activity-ktx:1.9.1")
    implementation("androidx.fragment:fragment-ktx:1.8.2")

    // ========== 测试依赖（可选）==========
    testImplementation("com.google.dagger:hilt-android-testing:2.51.1")
    kaptTest("com.google.dagger:hilt-compiler:2.51.1")
    androidTestImplementation("com.google.dagger:hilt-android-testing:2.51.1")
    kaptAndroidTest("com.google.dagger:hilt-compiler:2.51.1")
}

// 必须为 kapt 配置，否则 Hilt 注解处理失效
kapt {
    correctErrorTypes = true
}

2.4 kapt vs ksp：注解处理器选择

Hilt 编译器支持 kapt 和 ksp 两种处理方式。下表对比了差异，帮助你根据项目情况选择。

2.5 AndroidManifest.xml：声明 @HiltAndroidApp

Hilt 要求所有使用依赖注入的 Application 类被 @HiltAndroidApp 注解。确保在 AndroidManifest 中引用自定义 Application 类。

<!-- app/src/main/AndroidManifest.xml -->
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application
        android:name=".MyApplication"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.HiltViewModelSample">

        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>

</manifest>

同时在 MyApplication.kt 中注入 Hilt 入口：

// app/src/main/java/com/example/hiltviewmodelsample/MyApplication.kt
package com.example.hiltviewmodelsample

import android.app.Application
import dagger.hilt.android.HiltAndroidApp

@HiltAndroidApp
class MyApplication : Application()

2.6 版本兼容性矩阵与排查指南

版本不匹配是 Hilt 集成中最常见的失败原因。下表列出了本课程基准版本组合以及降级方案。

2.7 Gradle Sync 验证与调试

配置完成后，执行以下步骤验证环境准备就绪：

1. File → Sync Project with Gradle Files，确保无红色报错。
2. 在 Terminal 执行 ./gradlew assembleDebug，观察编译输出。

   # 成功标志（部分日志）
   > Task :app:kspDebugKotlin UP-TO-DATE
   > Task :app:compileDebugKotlin UP-TO-DATE
   > Task :app:compileDebugJavaWithJavac UP-TO-DATE
   > Task :app:mergeDebugAssets UP-TO-DATE
   ...
   BUILD SUCCESSFUL in 12s

3. 如果遇到 Unresolved reference: hilt 或 Cannot find symbol class HiltAndroidApp，常见原因为：
   • 插件未在模块级 build.gradle.kts 中 apply（缺少 id("com.google.dagger.hilt.android")）。
   • kapt/ksp 处理器未声明或处理器与 Hilt 版本不匹配。
   • IDE 缓存问题：执行 File → Invalidate Caches / Restart。

2.8 小结与最佳实践

完成本章配置后，你的项目已具备 Hilt + ViewModel 集成 的完整构建基础。确保以下关键点：

• 项目级插件声明：只使用 plugins { id(...) version ... apply false }，避免 buildscript 方式。
• 模块级应用插件：三个插件 com.android.application、com.google.dagger.hilt.android、com.google.devtools.ksp 必须顺序正确。
• 依赖声明：hilt-android 实现 + hilt-compiler 处理器，hilt-navigation-compose 用于 Compose 中获取 ViewModel。
• Application 类：@HiltAndroidApp + manifest 中 android:name 指向该类。
• 版本锁定期：固定 AGP / Kotlin / KSP 版本号，升级时逐个验证。