0Pricing
Kotlin Academy · 课时

将 KSP 处理器集成到 Gradle 构建中

在 Gradle 中配置 KSP，添加生成的源代码，并调试处理器输出。

将 KSP 处理器集成到 Gradle 构建中 是 CoddyKit 上的免费 Kotlin Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Kotlin Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Kotlin Academy 课程共包含 4 节课。

多模块结构

典型的 KSP 设置至少包含两个模块：:annotation（包含您的注解类）和 :processor（包含 SymbolProcessor）。使用方模块应用 KSP 插件，并声明 ksp 和 implementation 依赖项。

应用 KSP 插件

在使用方模块的 build.gradle.kts 中：

plugins {
    kotlin("jvm")  // or android, multiplatform
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

声明 ksp 依赖项

使用 ksp 配置（而不是 implementation）添加 KSP 处理器。该处理器仅在构建时运行，不会包含在最终构件中：

dependencies {
    implementation(project(":annotation"))
    ksp(project(":processor"))
}

生成的源代码目录

KSP 会将生成的文件写入 build/generated/ksp/<sourceSet>/kotlin/。KSP 插件会自动将这些目录添加到 Kotlin 源集，因此无需手动配置，您的代码就可以使用生成的类。

向处理器传递选项

通过 ksp { arg("key", "value") } 将构建时选项从 Gradle 传递给处理器。通过 environment.options["key"] 在处理器中读取这些选项：

// build.gradle.kts (consumer)
ksp {
    arg("generateMocks", "true")
    arg("outputPackage", "com.example.generated")
}

在处理器中读取选项

在 SymbolProcessorProvider.create() 方法中，从环境中访问选项：

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        val genMocks = environment.options["generateMocks"] == "true"
        return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
    }
}

增量构建

KSP 会跟踪输入与输出之间的依赖关系。调用 codeGenerator.createNewFile() 时，将每个生成的文件与其源符号关联起来。这样，当所跟踪的输入都未发生变化时，KSP 就会跳过重新处理。

val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)

Android 中的 KSP

对于 Android 项目，请在插件声明和依赖项声明中都将 kapt 替换为 ksp。如果需要让处理器在不同构建类型之间具有不同的行为，请使用 kspDebug 或 kspRelease 等按变体区分的配置。

Kotlin Multiplatform 中的 KSP

在 KMP 项目中，应用 KSP 插件，并根据处理器支持的目标平台，使用 add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor"))，或使用简写形式 kspCommonMainMetadata、kspJvmMain 等。

查看生成的文件

运行 ./gradlew build（Android 项目则运行 kspKotlin / kspDebugKotlin）后，检查 build/generated/ksp/。IntelliJ 和 Android Studio 会将这些文件夹标记为生成的源代码，并支持从使用处跳转到生成的声明。

调试处理器

使用 --debug 运行 Gradle 任务，或将 jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") 添加到 ksp 配置中，以便将远程调试器连接到注解处理 JVM。

快速检查

应使用哪个 Gradle 配置来添加一个在构建时运行、但不包含在运行时类路径中的 KSP 处理器？

回顾：将 KSP 集成到 Gradle 构建中

关键要点：

  • 应用 com.google.devtools.ksp 插件；通过 ksp() 依赖项添加处理器
  • 生成的源代码位于 build/generated/ksp/ 中，并会自动添加到源集
  • 通过 ksp { arg() } 从 Gradle 传递选项；通过 environment.options 读取这些选项
  • 将 Dependencies 与 createNewFile() 搭配使用，以实现准确的增量重新构建
  • 支持 Android（按变体配置）和 Kotlin Multiplatform

常见问题解答

「将 KSP 处理器集成到 Gradle 构建中」课时是免费的吗？

是的 — 「将 KSP 处理器集成到 Gradle 构建中」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Kotlin Academy 课程的其余内容，请升级到 CoddyKit PRO。 Kotlin Academy 课程共包含 4 节课。

「将 KSP 处理器集成到 Gradle 构建中」这节课中我会学到什么？

在 Gradle 中配置 KSP，添加生成的源代码，并调试处理器输出。 你通过在浏览器中直接运行的动手代码来练习 Kotlin Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Kotlin Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Kotlin Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。

「将 KSP 处理器集成到 Gradle 构建中」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Kotlin Academy 课中编写并运行代码吗？

能。每节 Kotlin Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. KSP 与 KAPT：KSP 为何更快
  2. 编写您的第一个 SymbolProcessor
  3. 使用 KotlinPoet 生成 Kotlin 源文件
  4. 将 KSP 处理器集成到 Gradle 构建中
← 返回 Kotlin Academy