本文介紹如何使用現代化方式安裝 Hilt。快速開始，請按照以下步驟執行：

安裝流程

版本資訊

目前已驗證的版本組合：

檔案架構圖

app/
├── src/
│   ├── main/
│   │   ├── java/com/example/app/
│   │   │   ├── MyApplication.kt     // @HiltAndroidApp
│   │   │   ├── MainActivity.kt      
│   │   │   └── di/                  
Gradle Scripts/
    ├── build.gradle.kts             // 專案層級
    ├── app/build.gradle.kts         // 應用模組層級
    └── gradle/libs.versions.toml    // 版本目錄

安裝步驟(注意：要按照順序來安裝)

1. 配置 Version Catalog，在 libs.versions.toml 中定義 Hilt和 KSP版本

    // libs.versions.toml
    [versions]
    hilt = "2.51.1"
    ksp = "1.9.21-1.0.15"
   
    [libraries]
    hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
    hilt-android-compiler = { group = "com.google.dagger", name = "hilt-android-compiler", version.ref = "hilt" }
   
    [plugins]
    hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
    ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
   

2. 專案層級配置 build.gradle.kts (Project name)

    // build.gradle.kts
    plugins {
        ...
        alias(libs.plugins.hilt) apply false
        alias(libs.plugins.ksp) apply false
    }
   

3. 應用模組配置 build.gradle.kts (Module : app)

    // build.gradle.kts
    plugins {
        ...
        alias(libs.plugins.hilt)
        alias(libs.plugins.ksp)
    }
    android {
        ...
        compileOptions {
                sourceCompatibility = JavaVersion.VERSION_17
                targetCompatibility = JavaVersion.VERSION_17
            }
            kotlinOptions {
                jvmTarget = "17"
            }
    }
   
    dependencies {
        ...
        implementation(libs.hilt.android)
        ksp(libs.hilt.android.compiler)
    }
   

4. 創建 Application 類別

   1. 檔案架構(跟 MainActivity 同層級)

       app/
       ├── src/
       │   ├── main/
       │   │   ├── java/com/example/app/
       │   │   │   ├── MyApplication.kt     // @HiltAndroidApp
       │   │   │   ├── MainActivity.kt      
       │   │   │   └── di/                  
       ...
      

   2. MyApplication.kt

       // MyApplication.kt
       ...
       @HiltAndroidApp
       class MyApplication : Application()
      

5. 在 AndroidManifest.xml 註冊:

    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.example.app">
   
        <application
            android:name=".MyApplication"  <!-- 加入這行 -->
            android:allowBackup="true"
            android:icon="@mipmap/ic_launcher"
            ...
        >
            <activity
                android:name=".MainActivity"
                ...
            </activity>
        </application>
    </manifest>
   

6. 同步與編譯

   1. Sync Project with Gradle Files

   2. Build > Clean Project

   3. Build > Rebuild Project

注意：完成編譯後可能會看到關於 deprecated API 的警告，這是 Hilt 生成代碼的問題，可以安全忽略。

7. 以上完成 Hilt安裝與基礎環境設定，接下來可以

   1. 在Activity中使用 @AndroidEntryPoint

   2. 在ViewModel中使用 @HiltViewModel

   3. 開始定義和注入依賴

常見問題處理

• 編譯警告(可忽略)

    Task :app:compileDebugJavaWithJavac
    Note: /Users/name/AndroidStudioProjects/.../app/build/generated/ksp/debug/java/com/.../.../Hilt_MyApplication.java uses or overrides a deprecated API.
    Note: Recompile with -Xlint:deprecation for details.
  

  • 這是 Hilt 生成代碼的問題。具體來說，Hilt_MyApplication.java 中使用了一些已過時的 API 。

  • 因這不是自己寫的代碼引起的，因此我想這是 Hilt 團隊需要解決的問題，可能在未來的版本會修復

版本相容性對照表連結

• Hilt 沒查到官方 GitHub 提供，但有開發者們的版本對照分享：

  • Kotlin:1.9.0 - Hilt:2.48、Kotlin:2.0.0 - Hilt:2.51.1

    • https://stackoverflow.com/questions/67744002/hilt-unsupported-metadata-version-in-kotlin

  • 官方 GitHub：https://github.com/google/dagger

• KSP ：https://github.com/google/ksp/releases

  • KSP 版本的前半部必須與使用的 Kotlin 版本相符。
    如果 Kotlin是 2.0.21，KSP 版本必須是 2.0.21-x.y.z 版本之一。

  • https://developer.android.com/build/migrate-to-ksp?hl=zh-tw#add-ksp

• JDK ：https://developer.android.com/build/jdks?hl=zh-tw#compileSdk

• AGP 與 Kotlin ：https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin

為什麼有這份指南

官方文檔經常過時且分散，故而產出此篇文章更符合現代化的整合安裝方案。

傳統 Hilt官方建議的安裝問題

• 未提供搭配 Version Catalog 的配置設定

• 使用kapt會產生警告訊息，執行Clean project > Rebuild 產生警告訊息：

    Task :app:kaptDebugUnitTestKotlin
    warning: The following options were not recognized by any processor: '[dagger.fastInit, dagger.hilt.android.internal.disableAndroidSuperclassValidation, dagger.hilt.android.internal.projectType, kapt.kotlin.generated]'
    The following options were not recognized by any processor: '[dagger.fastInit, dagger.hilt.android.internal.disableAndroidSuperclassValidation, dagger.hilt.android.internal.projectType, kapt.kotlin.generated]'
  

  • 這個警告是關於 Kapt 處理器的選項設定，官方建議逐漸遷移使用KSP，效率更快。詳情參考：https://developer.android.com/build/migrate-to-ksp?hl=zh-tw

更現代化的安裝方案

• KSP 替代 kapt

  • Android 官方推薦，提升編譯效率

  • 主流框架如 Room 等已支援 KSP

  • https://android-developers.googleblog.com/2021/09/accelerated-kotlin-build-times-with.html

• 升級至JDK 17

  • 適配 AGP 8.0 以上版本

• 使用 Version Catalog

  • 集中管理版本號

  • 避免版本衝突

  • 適合多模組專案

參考資源

Hilt 相關

• Hilt 版本對照討論：https://stackoverflow.com/questions/67744002/hilt-unsupported-metadata-version-in-kotlin

• Dagger 官方 GitHub：https://github.com/google/dagger

• 官方文件：https://developer.android.com/training/dependency-injection/hilt-android?hl=zh-tw#kts

KSP 相關

• KSP GitHub Releases：https://github.com/google/ksp/releases

• KSP 遷移指南：https://developer.android.com/build/migrate-to-ksp?hl=zh-tw#add-ksp

• KSP 效能改善說明：https://android-developers.googleblog.com/2021/09/accelerated-kotlin-build-times-with.html

JDK & Android Gradle Plugin

• Android JDK 環境要求：https://developer.android.com/build/jdks?hl=zh-tw#compileSdk

• Kotlin 與 AGP 版本對照：https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin