從 kapt 遷移至 KSP

注意： Kapt 目前處於維護模式，建議您針對所有支援 KSP 的處理器，從 kapt 遷移至 KSP。在大多數情況下，您只需要變更專案的建構設定即可遷移。

Kapt (Kotlin 註解處理工具) 可讓您將 Java 註解處理工具與 Kotlin 程式碼搭配使用，即使這些處理工具並未支援 Kotlin 也沒問題，方法是透過 Kotlin 檔案產生 Java 虛設常式，供這些處理工具讀取。產生這類虛設常式是相當耗費資源的作業，並會大幅影響建構速度。

KSP (Kotlin Symbol Processing) 是以 Kotlin 優先的 kapt 替代方案，KSP 可直接分析 Kotlin 程式碼，且速度可達 2 倍。此外，KSP 對於 Kotlin 的語言結構有更充分的瞭解。

您可於遷移期間在專案中並行執行 kapt 和 KSP，並可針對各個模組和各個程式庫逐一進行遷移。

注意： 如果模組中仍有 kapt 處理工具，該模組仍會產生虛設常式。這表示在大多數情況下，只有在模組完全停止使用 kapt 時，效能才會有所改善。

以下是遷移步驟總覽：

1. 確認您使用的程式庫是否支援 KSP
2. 在專案中新增 KSP 外掛程式
3. 使用 KSP 取代註解處理工具
4. 移除 kapt 外掛程式

確認您使用的程式庫是否支援 KSP

首先，請確認您目前搭配 kapt 使用的程式庫是否支援 KSP。許多熱門程式庫 (包括 Dagger、Glide、Room 和 Moshi) 都正在新增對 KSP 的支援。

您可以查看說明文件中的支援的程式庫清單，或參閱所用程式庫的說明文件和問題追蹤工具。

注意： 雖然傳統上不是隨附的程式庫依附元件，但資料繫結也會使用註解處理工具提供其功能，且目前沒有針對資料繫結提供 KSP 支援的計畫。如要降低 kapt 對建構作業的影響，您可以在不同模組中使用資料繫結。

在專案中新增 KSP 外掛程式

首先，請在頂層 build.gradle.kts 檔案中宣告 KSP 外掛程式，並確認所選 KSP 版本與專案的 Kotlin 版本一致。您可以在 KSP GitHub 頁面中查看版本清單。

注意： KSP 版本的前半部必須與建構中使用的 Kotlin 版本相符。舉例來說，如果您使用的是 Kotlin 2.0.21，KSP 版本必須是 2.0.21-x.y.z 版本之一。

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.0.21-1.0.27" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.0.21-1.0.27' apply false
}

接著在模組層級 build.gradle.kts 檔案中啟用 KSP：

Kotlin

plugins {
    id("com.google.devtools.ksp")
}

Groovy

plugins {
    id 'com.google.devtools.ksp'
}

使用 KSP 取代註解處理工具

啟用 KSP 後，您就能開始使用 KSP 取代 kapt。針對大部分的程式庫，您只需要在宣告依附元件時將 kapt 變更為 ksp 即可，原因是這兩者會在相同成果中提供其註解處理工具和 KSP 處理工具。

注意： 針對某些程式庫 (例如 Glide)，您可能還需要將依附元件變更至其他成果。請務必參閱程式庫的說明文件。

Kotlin

dependencies {
    kapt("androidx.room:room-compiler:2.5.0")
    ksp("androidx.room:room-compiler:2.5.0")
}

Groovy

dependencies {
    kapt 'androidx.room:room-compiler:2.5.0'
    ksp 'androidx.room:room-compiler:2.5.0'
}

遷移至 KSP 之後，請同步處理並建構專案，確認專案是否仍可正常運作。

以下列舉幾個需要留意的常見問題：

• 某些程式庫針對 kapt 和 KSP 支援的功能並不相同。如果程式碼在遷移後發生問題，請參閱程式庫的說明文件。
• 與 kapt 相比，KSP 的 Kotlin 類型資訊 (例如是否可為空值的相關資訊) 更加準確。這表示在類型要求方面，KSP 可能較明確。因此，除了更新建構檔案以外，您可能還需要稍微修正原始碼。
• 如果您先前透過引數傳遞至註解處理工具，則現在可能必須透過那些引數傳遞至 KSP。請注意，kapt 和 KSP 的引數格式可能並不相同。詳情請參閱 KSP 說明文件和所用程式庫的說明文件。

移除 kapt 外掛程式

當模組中已沒有 kapt 隨附的依附元件時，請移除 kapt 外掛程式。

注意： 如要在模組中啟用資料繫結，您也必須使用 kapt。在使用資料繫結的模組中，您無法移除 kapt。

如果您是在 plugins 區塊中宣告 kapt 外掛程式：

Kotlin

plugins {
    id("org.jetbrains.kotlin.kapt")
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.kapt'
}

如果 kapt 外掛程式使用 Groovy 的 apply plugin 語法：

apply plugin: 'kotlin-kapt'

您也必須移除與 kapt 相關的所有其他設定，例如：

Kotlin

kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy

kapt {
    correctErrorTypes true
    useBuildCache true
}

其他資源

• Kotlinlang.org 提供的 KSP 說明文件
• GitHub 的 KSP 頁面
• Kotlinlang.org 的 kapt 頁面 -->