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

直接接入 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。