Skip to content

從 kapt 遷移至 KSP ​

本指南說明如何將註解處理器從 Kotlin 註解處理工具 (kapt) 遷移至 Kotlin 符號處理 (KSP)。您的專案可以充分利用 Kotlin 的語言特性並提升建置效能。

kapt 讓您可以在 Kotlin 中使用 Java 註解處理器。它會將 Kotlin 原始碼轉換為 Java「虛設常式」(stubs),然後在這些虛設常式上執行註解處理器。然而,這個過程開銷龐大,會大幅增加建置時間,並且在轉換過程中遺失某些 Kotlin 特有的特性。

相較之下,KSP 是專為 Kotlin 設計的 kapt 替代方案。KSP 藉由直接分析 Kotlin 原始碼並公開諸如可 null 性等 Kotlin 特有資訊,進而減少建置時間。

開始之前 ​

檢查專案中的處理器是否支援 KSP。請參閱支援的庫清單,或查閱相關文件。

KSP 與 kapt 可以並行執行,因此您可以分階段遷移專案,一次遷移一個程式庫或模組。

將 KSP 外掛程式新增至您的專案 ​

將 KSP 外掛程式新增至專案層級 build.gradle(.kts) 檔案中的 plugins {} 區塊:

kotlin
// build.gradle.kts

plugins {
    id("com.google.devtools.ksp") version "2.3.12" apply false
}
groovy
// build.gradle

plugins {
    id 'com.google.devtools.ksp' version '2.3.12' apply false
}

若要尋找最新版本的 KSP,請查看 GitHub 的 Releases。

在模組中將 kapt 替換為 KSP ​

找到使用您要遷移的處理器的模組。在該模組的 build.gradle(.kts) 檔案中:

  1. 將 KSP 外掛程式新增至 plugins {} 區塊:

    kotlin
    // build.gradle.kts
    
    plugins {
        id("com.google.devtools.ksp")
    }
    groovy
    // build.gradle
    
    plugins {
        id 'com.google.devtools.ksp'
    }
  2. 在 dependencies {} 區塊中,將 kapt 替換為 ksp:

    kotlin
    // build.gradle.kts
    
    dependencies {
        implementation("com.google.dagger:dagger:2.48")
    
        // 替換 kapt("com.google.dagger:dagger-compiler:2.48")
        ksp("com.google.dagger:dagger-compiler:2.48")
    }
    groovy
    // build.gradle
    
    dependencies {
        implementation 'com.google.dagger:dagger:2.48'
    
        // 替換 kapt 'com.google.dagger:dagger-compiler:2.48'
        ksp 'com.google.dagger:dagger-compiler:2.48'
    }

對於大多數程式庫而言,這項替換已足夠。請查閱各程式庫的文件,以確認是否需要進行任何額外的變更。

移除 kapt 外掛程式 ​

將所有處理器遷移至 KSP 後,您可以安全地從所有 build.gradle(.kts) 檔案中移除 kapt 外掛程式:

kotlin
// build.gradle.kts

plugins {
    // 移除 kapt 外掛程式宣告:
    id("org.jetbrains.kotlin.kapt")
}
groovy
// build.gradle

plugins {
    // 移除 kapt 外掛程式宣告:
    id 'org.jetbrains.kotlin.kapt'
}

刪除任何殘留的 kapt 配置(若有的話,例如 kapt {} 區塊)。

請參閱 ​