KSP迁移需满足AGP 9.0.1+、Gradle 9.1.0+、Kotlin Gradle Plugin 2.3.0+、KSP 2.3.6、JDK 17+及Android Studio Otter 3+，且必须使用Kotlin DSL；Room等注解处理器需换为ksp专用artifact，彻底移除kapt残留。

确认当前环境是否满足KSP最低要求

不满足版本底线，ksp 插件根本加载不起来，报错往往指向 plugin not found 或 unresolved reference，而不是配置问题。2026年10月的稳定组合是：

• AGP 9.0.1+（AGP 9.0.0 有已知插件注册冲突）
• Gradle 9.1.0+（低于此版本会直接拒绝启动）
• Kotlin Gradle Plugin 2.3.0+（2.3.1 起才正式支持 AGP 9.0 + KSP 协同）
• KSP 2.3.6（2.3.1 是底线，但 2.3.3 起已弃用旧 API，建议跳过中间版本）
• JDK 17+（IDE 和 Gradle 构建都强制要求）

特别注意：Android Studio 必须是 Otter 3 (2025.2.3) 或更新版；IntelliJ IDEA 当前仍不支持 AGP 9.0 的 Android 模块构建，别在 IDEA 里试。

检查项目是否已切换到 Kotlin DSL（.gradle.kts）

ksp 不支持 Groovy DSL（.gradle 文件），这是硬性限制。第一次迁移失败最常见的原因就是还在用 build.gradle。迁移本身不难，但要注意三点：

• 所有 build.gradle 必须重命名为 build.gradle.kts
• 原 Groovy 中的 apply plugin: 'kotlin-kapt' 要改为 Kotlin DSL 的 plugins { id("org.jetbrains.kotlin.kapt") }（仅过渡期临时保留）
• 依赖块中的 kapt 声明（如 kapt libs.room.compiler）必须等后续步骤再改，不能提前删——否则编译直接失败

如果项目用了 version catalogs（libs.versions.toml），确认其中的 ksp 对应 artifact 已声明，例如：ksp = "com.google.devtools.ksp:com.google.devtools.ksp.gradle.plugin"。

逐个验证注解处理器库是否提供 KSP 支持

不是所有带 @Inject、@Entity 的库都能直接换。关键看它是否发布了 ksp classifier 的 processor 或独立 artifact：

• room-compiler → 改用 room-ksp（artifactId 不同）
• dagger-compiler → 直接换 ksp 依赖即可（同一 artifact，classifier ksp）
• moshi-kotlin-codegen → 改为 moshi-ksp
• glide → 需升级到 4.15.0+ 并使用 glide-ksp artifact
• data binding → 不支持 KSP，且无计划支持；必须保留在独立模块中，或考虑迁移到 ViewBinding

查证方式很简单：打开对应库的 Maven Central 页面，搜索 artifact 是否含 ksp 字样；或者翻其 GitHub README，通常会在 “KSP Support” 小节写明。

移除 kapt 插件并清理残留配置

只有彻底清掉 kapt，KSP 才能发挥全部加速效果。残留一个 kapt 依赖，就会触发 Java stub 生成，拖垮整个模块构建速度：

• 从 build.gradle.kts 中删掉 org.jetbrains.kotlin.kapt 插件声明
• 删掉所有 kapt 依赖行（如 kapt libs.dagger.compiler），替换成对应 ksp 形式
• 删掉 kapt { ... } 块（比如 correctErrorTypes = true 这类配置，KSP 不兼容）
• 检查 androidComponents DSL 中是否还有 beforeVariants 之类对 kapt 的 hook，一并清理

最容易被忽略的是：多模块项目中，某个子模块忘了改，结果主模块提速了，那个子模块还是慢得离谱——Build Scan 里看 kaptGenerateStubs Task 是否还存在，是最终验真手段。