12.4.3 从 kapt 迁移到 KSP

2 分钟阅读

原文链接: https://kotlinlang.org/docs/ksp-kapt-migration.html

12.4.3 从 kapt 迁移到 KSP

在本指南中，你将学习如何把注解处理器从 kapt 迁移到 KSP，从而让项目充分利用 Kotlin 特性并提升构建性能。

kapt（Kotlin 注解处理工具）是一个有用的工具，让你可以在 Kotlin 中使用 Java 注解处理器。它的工作方式是把 Kotlin 源代码翻译成 Java “桩文件”，然后在这些桩文件上运行注解处理器。不过，这个过程开销很大，会显著增加构建时间，并且在翻译过程中会丢失一些 Kotlin 特有的特性。

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

开始之前，请确认你项目中的处理器是否支持 KSP。请参阅受支持的库列表，或查阅它们的文档。

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

向项目添加 KSP 插件

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

Kotlin

1
2
3
plugins {
    id("com.google.devtools.ksp") version "2.3.10" apply false
}

Groovy

1
2
3
plugins {
    id 'com.google.devtools.ksp' version '2.3.10' apply false
}

提示： 要查找 KSP 的最新版本，请查看 GitHub 的 Releases。

更新你的处理器

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

把 KSP 添加到 plugins {} 块中：

Kotlin

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

Groovy

1
2
3
    plugins {
        id 'com.google.devtools.ksp'
    }

在 dependencies {} 块中，把 kapt 替换为 ksp：

Kotlin

1
2
3
4
5
6
7
    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")
    }

Groovy

1
2
3
4
5
6
7
    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 插件：

Kotlin

1
2
3
4
plugins {
   // 删除这一行：
    id("org.jetbrains.kotlin.kapt")
}

Groovy

1
2
3
4
plugins {
    // 删除这一行：
    id 'org.jetbrains.kotlin.kapt'
}

如果你还有遗留的 kapt 配置，请一并删除。

接下来学什么？

在 KSP 入门中学习如何编写自己的基于 KSP 的注解处理器。
在 KSP 仓库中探索使用 KSP 的示例项目。
在概览中进一步了解 KSP。

最后修改 September 13, 2026: 更新C和Cpp以及新增Kotlin和SwiftUI (d20dcaaa6)