旧文章中的 1.9.24-1.0.20 是 Kotlin 1.9 / KSP 1.x 时期的配置。升级 Kotlin 2.x 后，应该先确认项目使用的 KSP 实现和处理器兼容性，再处理生成代码与增量编译；不要只把旧版本号改成另一个数字。
KSP2 改变了什么
KSP2 是 KSP API 的新实现。它不再作为 Kotlin 编译器插件运行，而是基于 Kotlin 与 IntelliJ 等工具共用的编译器 API。这个方向与 K2 编译器迁移有关，处理器作者和使用者都需要重新核对处理行为、Gradle 任务和兼容矩阵。
这不意味着所有 KSP1 处理器都必然失效。是否能直接迁移，取决于处理器使用的 API、依赖版本、项目的 Kotlin/Gradle/Android Gradle Plugin 组合，以及生成代码有没有依赖旧实现的行为。
更新 Gradle 插件和处理器依赖
先查看 KSP 官方 Releases 中与你项目工具链匹配的版本。以本文核对日期为准，官方 Releases 页面列出的最新版本是 2.3.12；具体项目仍要按该版本说明检查最低 Android Gradle Plugin、Gradle 和 Kotlin 要求，不能把“最新”当成兼容性保证。
版本目录示例：
[versions]
ksp = "2.3.12"
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }在 Android 模块中应用插件，并把代码生成器依赖放到 ksp configuration：
plugins {
alias(libs.plugins.kotlin.android)
alias(libs.plugins.ksp)
}
dependencies {
implementation(libs.moshi)
ksp(libs.moshi.codegen)
}上面只是 Gradle 写法示意。Kotlin Gradle Plugin、AGP、Gradle Wrapper 与处理器库都要按各自发布说明核对；不要继续照抄旧文中的 Kotlin 1.9 和 KSP1 版本组合。
检查处理器与生成结果
升级后先确认处理器可以解析工程里的 Kotlin 符号，再查看生成目录和编译错误。重点检查：
- 是否正确处理暂时无法解析的符号，并在后续 processing round 中重试。
- 生成文件的
Dependencies是否准确声明输入文件；错误地标成 isolating 或 aggregating 会影响增量编译。 - 是否依赖 KSP1 的内部实现细节、Java Stub 或未承诺稳定的解析行为。
- Java 与 Kotlin 混合源码、泛型、类型别名、错误类型和多模块依赖是否仍能得到预期结果。
迁移验证可按这个顺序执行：
- 用项目当前选定的 KSP2 版本运行
./gradlew :app:kspDebugKotlin。 - 检查生成代码，再运行对应模块的
assembleDebug和已有测试。 - 修改或删除一项带处理器注解的源码，确认增量构建能更新或清理对应生成文件。
- 用 CI 中实际使用的 Gradle Wrapper 和 JDK 重跑，避免本机与构建环境差异。
这些是建议的检查步骤；本文没有在某个仓库或设备上执行迁移。
Kotlin Multiplatform 项目要单独检查
KMP 项目的 KSP 配置也在演进。KSP Release notes 已提示将通用的 ksp(...) 配置迁移到 target-specific configuration。若工程包含多个 target，不要直接复制 Android 单模块示例；按当前 KSP 项目文档 和所用版本的发布说明逐个核对需要处理的 target。
何时保留旧 KSP1 文档
仍在维护 Kotlin 1.9 / KSP1 工程时，旧文中的 Processor API 示例可以作为历史参考。新工程或升级中的工程应以当前 KSP2 文档为准。遇到构建失败时，先记录 Kotlin、AGP、Gradle、KSP 和处理器版本，再根据错误定位版本兼容或处理器 API 问题。