Gradle Kotlin项目怎么接入KSP处理器-java教程-PHP中文网

KSP接入需三步：声明插件、配置依赖、注册处理器；必须用Kotlin DSL，symbol-processing-api须与Kotlin版本严格匹配，且仅限implementation依赖，META-INF/services路径和类名须完全正确，同时彻底移除kapt。

gradle kotlin项目怎么接入ksp处理器

直接接入 KSP 处理器，核心就三步：声明插件、配置依赖、注册处理器。跳过 kapt 的 Java stub 生成环节，编译速度能明显提升，但配置错一个地方就可能 silent fail 或根本不触发处理。

Gradle 插件必须用 Kotlin DSL（.gradle.kts）

KSP 官方不支持 Groovy 脚本。如果你的 build.gradle 还是 Groovy 格式，KSP 插件加载会失败，且没有任何明确报错——只会默默跳过处理。

把根目录 build.gradle 重命名为 build.gradle.kts
把模块级 build.gradle 同样重命名为 build.gradle.kts

在根 build.gradle.kts 中声明插件（推荐方式）：

plugins {
    id("com.google.devtools.ksp") version "2.3.4" apply false
}

ksp 依赖要加在 processor 模块的 implementation 里

很多人把 symbol-processing-api 加在注解模块或 app 模块，结果 SymbolProcessor 类找不到、process() 方法不执行——因为 KSP 运行时只扫描 implementation 依赖中的处理器提供者。

ImageMagick 批处理处理器

使用 ImageMagick 的 convert 和 mogrify 命令进行批量图像处理，支持调整大小、裁剪、水印和格式转换。与 libvips 集成以实现高性能缩略图生成。

下载

确保 processor 模块（如 router-processor）的 build.gradle.kts 包含：

dependencies {
    implementation("com.google.devtools.ksp:symbol-processing-api:2.3.4")
    implementation("com.squareup:kotlinpoet:1.12.0")
    implementation(project(":router-annotations"))
}

symbol-processing-api 版本必须与你项目使用的 Kotlin 编译器版本严格匹配（例如 Kotlin 2.3.4 → KSP 2.3.4）
不要用 api 或 compileOnly，否则 META-INF/services/... 文件不会被正确打包

META-INF/services 文件名和内容不能有空格或大小写错误

KSP 通过 Java SPI 机制发现处理器，路径或类名错一个字符，就会完全不加载你的 SymbolProcessorProvider，也没有日志提示。

文件路径必须是：src/main/resources/META-INF/services/com.google.devtools.ksp.processing.SymbolProcessorProvider
文件内容必须是处理器提供者的**全限定类名**，例如：
```
com.example.router.RouterProcessorProvider
```
类名末尾不能有多余空行、BOM 字符、中文空格；大小写必须与实际类完全一致
该类必须实现 SymbolProcessorProvider 接口，并在 create() 中返回你的 SymbolProcessor 实例

最容易被忽略的是：只要模块里还残留任意一个 kapt 依赖（比如 kapt "androidx.room:room-compiler"），Gradle 就仍会为整个模块生成 Java stub，KSP 的性能优势就基本归零。务必清干净所有 kapt 行，再把对应依赖改成 ksp。