从 kapt 迁移到 KSP
在这篇指南中, 你将学习如何将注解处理器从 kapt 迁移到 KSP, 以便充分利用 Kotlin 的功能特性, 并改善构建性能.
kapt (Kotlin Annotation Processing Tool) 是一个有用的工具, 可以在 Kotlin 中使用 Java 注解处理器. 它的工作方式是将 Kotlin 源代码翻译为 Java "桩(stub)" 文件, 然后在这些桩文件上运行注解处理器. 但是, 这个过程代价高昂, 会显著增加构建时间, 并且在翻译过程中会丢失一些 Kotlin 特有的功能特性.
相比之下, KSP (Kotlin Symbol Processing) 是 kapt 的替代方案, 专为 Kotlin 而设计. KSP 了解所有的 Kotlin 功能特性, 并直接分析源代码, 从而缩短构建时间.
在开始之前, 请检查你的项目中的注解处理器是否支持 KSP. 请查看 支持的库 列表, 或查阅注解处理器的文档.
向你的项目添加 KSP plugin
在项目级的 build.gradle(.kts) 文件的 plugins {} 代码块中, 添加 KSP:
plugins {
id("com.google.devtools.ksp") version "2.3.9" apply false
}
plugins {
id 'com.google.devtools.ksp' version '2.3.9' apply false
}
更新处理器
找到使用你想要迁移的处理器的模块. 在这个模块的 build.gradle(.kts) 文件中进行以下修改:
在
plugins {}代码块中, 添加 KSP:plugins { id("com.google.devtools.ksp") }plugins { id 'com.google.devtools.ksp' }在
dependencies {}代码块中, 将kapt替换为ksp: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 plugin
将所有的处理器迁移到 KSP 之后, 可以安全地从所有的构建文件中移除 kapt plugin:
plugins {
// 删除这一行:
id("org.jetbrains.kotlin.kapt")
}
plugins {
// 删除这一行:
id 'org.jetbrains.kotlin.kapt'
}
如果还有残留的 kapt 配置, 也一起删除.
下一步做什么?
2026/08/12