Skip to content

从 kapt 迁移到 KSP ​

本指南介绍如何将注解处理器从 Kotlin 注解处理工具 (kapt) 迁移到 Kotlin Symbol Processing (KSP)。迁移后,你的项目可以充分利用 Kotlin 的语言功能并提升构建性能。

kapt 允许你在 Kotlin 中使用 Java 注解处理器。它会将 Kotlin 源代码转换为 Java“存根 (stub)”,然后在这些存根上运行注解处理器。但是,该过程开销很大,会显著增加构建时间,并且在转换过程中会丢失某些 Kotlin 特有的功能。

相比之下,KSP 是专为 Kotlin 设计的 kapt 替代方案。KSP 通过直接分析 Kotlin 源代码并公开诸如为 null 性 (nullability) 等特定于 Kotlin 的信息,从而减少构建时间。

开始之前 ​

检查项目中的处理器是否支持 KSP。请参阅支持的库列表或查阅其相关文档。

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

将 KSP 插件添加到你的项目 ​

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

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 {} 块(如果存在)。

另请参阅 ​