从 kapt 迁移到 KSP

注意 ：kapt 目前处于维护模式，因此我们建议您将所有支持 KSP 的处理器从 kapt 迁移到 KSP。在大多数情况下，迁移只需更改项目的 build 配置。

借助 kapt（Kotlin 注解处理工具），您可以将 Java 注解处理器与 Kotlin 代码搭配使用，即使这些处理器没有特定的 Kotlin 支持也是如此。方法是从 Kotlin 文件生成 Java 桩，然后处理器就可以读取这些桩。生成桩是一项成本高昂的操作，并且对构建速度有很大影响。

KSP (Kotlin Symbol Processing)是以 Kotlin 优先的 kapt 替代方案。KSP 可直接分析 Kotlin 代码，使得速度提高多达 2 倍。此外，它还可以更好地了解 Kotlin 的语言结构。

在迁移期间，您可以在项目中同时运行 kapt 和 KSP，并且您可以逐个模块、逐个库完成迁移。

注意：如果模块中有任何剩余的 kapt 处理器，系统仍会在该模块中生成桩。这意味着，只有从模块中彻底移除所用的 kapt 后，大部分性能改进才能实现。

下面简要介绍了迁移步骤：

1. 检查您使用的库是否已支持 KSP
2. 将 KSP 插件添加到您的项目中
3. 将注释处理器替换为 KSP
4. 移除 kapt 插件

检查您使用的库是否已支持 KSP

首先，检查与 kapt 搭配使用的库是否已支持 KSP。许多热门库（包括 Dagger、Glide、Room 和 Moshi）已支持 KSP，而其他一些库正在添加支持。

您可以查看文档中的支持的库列表，或者参阅您所用库的文档和问题跟踪器。

注意：虽然数据绑定不是传统上会被包含的库依赖项，但数据绑定也使用注解处理器提供其功能，而目前没有针对数据绑定提供 KSP 支持的计划。通过将数据绑定与单独的模块一起使用，可以减轻 kapt 对 build 的影响。

将 KSP 插件添加到您的项目中

首先，在顶级 build.gradle.kts 文件中声明 KSP 插件。请务必选择与项目的 Kotlin 版本一致的 KSP 版本。您可以在 KSP GitHub 页面上找到版本列表。

注意 ：KSP 版本的前一部分必须与 build 中使用的 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 使用完全相同的功能集。如果您的代码在迁移后出现异常，请参阅相应库的文档。
• KSP 的 Kotlin 类型信息比 kapt 更准确（例如有关是否可为 null 的信息），这意味着 KSP 处理器对于类型要求更为精确。因此，除了更新 build 文件之外，您可能还需要对源代码进行一些修复。
• 如果您之前将参数传递给注解处理器，您现在可能需要将这些参数传递给 KSP。请注意，kapt 和 KSP 的参数格式可能有所不同。如需了解详情，请参阅 KSP 文档并查阅所用库的文档。

移除 kapt 插件

如果您的模块中的依赖项不再包含 kapt，请移除 kapt 插件。

注意：数据绑定仍需要在模块中启用 kapt。在使用数据绑定的模块中，不能移除 kapt。

如果已在插件块中声明 kapt：

Kotlin

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

Groovy

plugins {
    id 'org.jetbrains.kotlin.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 ->