其实，

KSP能否替代kapt？

使用者痛点回顾

在日常 Android 开发中。很多团队面临以下痛点：

• 建立时间长，特别是老项目每次全量编译耗时数十分钟。
• 内存使用高，导致 IDE 卡顿甚至 OOM 崩溃。说起来，
• 插件兼容性差。升级 Gradle 或 AGP 时常出现错误。
• 注解处理器迁移成本高，旧代码依赖 kapt 的库难以改动。
• 增量编译失效，修改小文件仍触发大范围重编译。

建立速度调整

老项目常见慢建立原因

老项目建立慢通常卡在这几个地方，按效果从大到小排列：

快速检查清单

org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Xmx4096m -XX:+HeapDumpOnOutOfMemoryError
org.gradle.configuration-cache=true
android.useAndroidX=true
android.nonTransitiveRClass=true

KAPT 替换为 KSP 的最小代码改动示例

// build.gradle.kts
plugins {
// id ← 删掉
id version ".x."
}
dependencies {
// kapt ← 删掉
ksp
}

Simplify & Troubleshoot Tips

• •KSP 更快的原因：KSP 是 Kotlin 原生符号处理器。只解析 Kotlin 源码，无需先把代码编译成 Java byte‑code，再进行注解处理。相比完整的 Java 注解处理器，省去了大量不必要的编译步骤。
• •AOT & Incremental Support：KSP 原生支持增量化生成；只要你使用了 `android.nonTransitiveRClass=true`。 每个 module 会生成自己的 R 类，从而进一步缩小重编译范围。话说回来，
• •插件兼容性检查：`configuration-cache` 在 Gradle 7+ 中已稳定可用。但要求所有脚本使用 Kotlin DSL 且没有不兼容插件。先执行一次 `./gradlew clean build --stacktrace` 看是否报错，再开启缓存。
• •Migrate Annotation Libraries：- Room、Hilt、ButterKnife 等主流库已经发布了对应的 KSP 版本；如果还有自定义注解处理器，请检查其是否已提供 `ksp` 模块或自行实现简单的 KAPT‑to‑KSP 包装层。
• •Migrating Legacy Projects：- 从 kapt 到 KSP 的迁移成本低：仅需删除 `.kapt` 插件引用并改为 `.ksp` 即可；若项目结构复杂，可先在一个子模块试点，接下来逐步推广到整个代码库。
• •Avoiding “Missing Symbol”的错误：- 确认所有依赖都声明在 `api {}` 或 `implementation {}` 中，而且没有冲突版本；保持 `kotlin` 与 `kotlin` 的版本一致，以免引起符号解析错误。老实说，
• •Troubleshooting “Could not resolve all task dependencies for configuration ‘classpath’”：- 检查网络代理、仓库地址及 Maven Central 是否可访问；确保所有 plugin 均使用同一版本号，以避免多重冲突导致的缺失类错误。• 在 Gradle 8.x 中，一些旧版插件会报错。需要升级到最新稳定版或寻找社区维护的 fork。• 如果你在 CI 环境遇到 OOM，请尝试增大 `GRADLE_OPTS=-Xmx8192m -XX:+HeapDumpOnOutOfMemoryError` 或分离测试/打包任务。• 对于 “Cannot read field 'xxx' of null object”，往往是由于 kapt 在某些情况会提前生成空实现类导致。可以尝试在 Gradle 脚本里添加： gradle tasks.withType.configureEach { kotlinOptions.freeCompilerArgs += } 来防止这种异常。

  ---

  小结

  • KSP 可以完全取代 kapt——只要相关注解处理器已经提供了 KSP 版本或自行适配即可。话说回来，
  • 通过配置缓存、并行编译和增量化可以让旧项目瞬间获得几倍以上的建立速度提高。
  • 记住升级 Gradle/AGP 前先备份，并逐步验证每个模块是否正常工作。

  继续关注我们关于 Java Android 老项目迁移系列的更新，让你摆脱繁琐手动迁移和频繁 OOM 的痛苦！