从 kapt 迁移到 KSP

在本指南中，你将学习如何将注解处理器从 kapt 迁移到 KSP，以便你的项目能够充分利用 Kotlin 的功能并提高构建性能。

kapt (Kotlin Annotation Processing Tool) 是一款非常有用的工具，它允许你在 Kotlin 中使用 Java 注解处理器。它的工作原理是将 Kotlin 源代码翻译成 Java “存根” (stub)，然后在这些存根上运行注解处理器。然而，这一过程开销巨大，会显著增加构建时间，并且在翻译过程中会丢失一些 Kotlin 特有的功能。

相比之下，KSP (Kotlin Symbol Processing) 是专为 Kotlin 设计的 kapt 替代方案。KSP 理解所有 Kotlin 功能并直接分析源代码，从而缩短构建时间。

在开始之前，请检查项目中的处理器是否支持 KSP。请参阅支持的库列表或查阅其文档。

KSP 和 kapt 可以并行运行，因此你可以分阶段迁移项目，一次迁移一个库或模块。

将 KSP 插件添加到项目中

在项目级的 build.gradle(.kts) 文件的 plugins {} 块中添加 KSP：

KotlinGroovy

plugins {
    id("com.google.devtools.ksp") version "2.3.3" apply false 
}

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

要查找 KSP 的最新版本，请查看 GitHub 的 Releases 页面。

更新处理器

找到使用要迁移的处理器的模块。在该模块的 build.gradle(.kts) 文件中：

1. 将 KSP 添加到 plugins {} 块：

   KotlinGroovy

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

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

2. 在 dependencies {} 块中，将 kapt 替换为 ksp：

   KotlinGroovy

   dependencies {
       implementation("com.google.dagger:dagger:2.48")
       // kapt("com.google.dagger:dagger-compiler:2.48")
       
       // KSP 处理器依赖项:
       ksp("com.google.dagger:dagger-compiler:2.48") 
   }

   dependencies {
       implementation 'com.google.dagger:dagger:2.48'
       // kapt 'com.google.dagger:dagger-compiler:2.48'
       
       // KSP 处理器依赖项:
       ksp 'com.google.dagger:dagger-compiler:2.48'
   }

对于大多数库，这种替换就足够了。请查看每个库的文档，了解是否需要进行任何额外更改。

移除 kapt 插件

在将所有处理器迁移到 KSP 后，你可以安全地从所有构建文件中移除 kapt 插件：

KotlinGroovy

plugins {
   // 删除此行：
    id("org.jetbrains.kotlin.kapt")
}

plugins {
    // 删除此行：
    id 'org.jetbrains.kotlin.kapt'
}

删除所有遗留的 kapt 配置（如果有的话）。

后续步骤

• 在快速入门 KSP中了解如何制作自己的基于 KSP 的注解处理器。
• 在 KSP 仓库中探索使用 KSP 的示例项目。
• 在概览中阅读更多关于 KSP 的信息。