告别 KAPT，拥抱 KSP：一次工具链迁移让构建提速 40%

如果你的 Android 项目还在用 KAPT每次./gradlew build都要盯着进度条发呆——这篇文章你应该看完。Moshi 2.0 alpha 刚宣布彻底放弃 KAPTKotlin 2.3.20 把 KSP 推上了新的成熟度Hilt、Room、Retrofit 的 KSP 适配也早已 stable。这一波工具链升级的时机已经到了。这篇文章不讲原理只讲迁移路径、踩坑记录和实测收益。① 为什么 KAPT 已经是瓶颈KAPTKotlin Annotation Processing Tool在 2017 年诞生时是一个临时方案——把 Java APT 的接口桥接到 Kotlin代价是每次注解处理都要先把 Kotlin 代码编译成 Java stub再交给注解处理器。这个 stub 生成过程是串行的、不可并行的而且无法增量。也就是说改一行代码 → 全量重新生成 stub → 注解处理器全量重跑多个 KAPT 处理器顺序执行无法并行构建缓存Gradle Build Cache命中率低CI 加速效果差在中大型项目中KAPT 相关任务往往占据30-50% 的全量构建时间。Room 的 DAO 处理、Hilt 的依赖注入代码生成、Moshi/Gson 的适配器……每一个都是 KAPT 任务叠加起来非常可观。② KSP 的核心差异KSPKotlin Symbol Processing是 JetBrains 2021 年推出的正式替代方案。它直接在 Kotlin 编译器的 AST抽象语法树层面工作跳过了 Java stub 生成。打个比方KAPT 就像你每次改一张 PPT都要先把它打印成纸质版、让别人手抄一遍再处理然后你才能拿到结果。KSP 直接在原文件上批注中间那道多余的打印 → 手抄流程消失了。更形象地说KAPT 是用了九年的 USB-A 转接头——凑合能用但原生接口早就该上了。Kotlin 源文件↓KAPT 路径旧Kotlin →Java Stub 生成串行耗时→ Java APT 处理 → 生成代码KSP 路径新Kotlin →直接读取 KSP API增量可并行→ 生成代码↓编译产物关键收益对比维度KAPTKSP增量编译❌ 不支持✅ 支持并行处理❌ 串行✅ 多处理器并行Java 互操作✅ 原生支持⚠️ 有限支持Build Cache 友好度低高Kotlin Multiplatform❌ 不支持✅ 原生支持③ 迁移实战主流库的 KSP 配置以下是当前2026年初主流库的 KSP 迁移状态和配置3.1 Hilt依赖注入Hilt KSP 支持已 stablehilt-android 2.51迁移步骤// build.gradle.kts (root) plugins { id(com.google.devtools.ksp) version 2.0.21-1.0.28 apply false } // app/build.gradle.kts plugins { // 移除 KAPT // id(kotlin-kapt) id(com.google.devtools.ksp) id(com.google.dagger.hilt.android) } dependencies { implementation(com.google.dagger:hilt-android:2.51.1) // kapt(com.google.dagger:hilt-compiler:...) → 改为: ksp(com.google.dagger:hilt-compiler:2.51.1) }3.2 Room本地数据库Room 2.6.0 正式支持 KSP需注意room.schemaLocation配置方式有变化dependencies { implementation(androidx.room:room-runtime:2.6.1) ksp(androidx.room:room-compiler:2.6.1) } // 旧 KAPT 配置 // kapt { // arguments { arg(room.schemaLocation, $projectDir/schemas) } // } // KSP 新配置方式 ksp { arg(room.schemaLocation, $projectDir/schemas) arg(room.incremental, true) // 启用增量处理 }3.3 MoshiJSON 序列化随着 Moshi 2.0 alpha 完全抛弃 KAPT生产版本1.15.x也已支持 KSP且从 KAPT 迁移时无需修改业务代码// 移除旧的 KAPT 处理器 // kapt(com.squareup.moshi:moshi-kotlin-codegen:1.15.1) // 添加 KSP 处理器 ksp(com.squareup.moshi:moshi-kotlin-codegen:1.15.1)④ K2 编译器构建加速的另一个杠杆Kotlin 2.3.20 里K2 编译器已完全稳定。如果你的项目还没开启这是迁移 KSP 后的下一个优化点。K2 的核心优化是前端编译器重写——类型检查、符号解析、控制流分析都做了算法级优化。JetBrains 官方数据K2 在大型项目的全量构建中比 K1 快15-30%增量编译快20-40%。说句直话如果你的 CI 构建超过 10 分钟还没迁 KSP、没开 K2这不是技术债是管理失职。工具已经成熟迁移成本极低继续拖下去的唯一理由就是优先级排不上——而这个借口在每天浪费几十人次构建等待时间的背景下说不过去。开启方式极简// gradle.properties kotlin.jvm.target.validation.modewarning // K2 编译器在 Kotlin 2.0 默认开启确认版本即可 // 验证当前编译器版本 // ./gradlew :app:compileDebugKotlin --info | grep Using Kotlin需要关注的兼容性问题部分 Kotlin 编译器插件如 Parcelize、Serialization需确认版本与 K2 对齐如果用到了某些依赖反射行为的库需测试回归Compose Compiler 2.0 原生支持 K2更新即可⑤ Monorepo 下的工具链运维几个关键配置在多模块/Monorepo 项目中KSP 的配置有一些额外注意点。5.1 Convention Plugins 统一 KSP 版本多模块项目最怕的是各模块自己维护处理器版本导致版本漂移和构建缓存失效。推荐用buildSrc或 Composite Build 的 Convention Plugin 统一管理// buildSrc/src/main/kotlin/android-ksp-convention.gradle.kts plugins { id(com.google.devtools.ksp) } // 统一的 KSP 参数配置 ksp { arg(correctErrorTypes, true) } // 各业务模块只需 plugins { id(android-ksp-convention) }5.2 CI 构建优化利用 KSP 增量提速KSP 的增量处理配合 Gradle Build Cache 可以显著减少 CI 时间。典型 pipeline 配置代码提交↓Gradle Build Cache 恢复↓KSP 增量处理仅变更文件↓并行任务分支A→ 单元测试分支B→ Lint 检查 APK 编译↓产物归档 Cache 写回关键gradle.properties配置org.gradle.cachingtrue org.gradle.paralleltrue org.gradle.configureondemandtrue org.gradle.jvmargs-Xmx4g -XX:UseParallelGC ksp.incrementaltrue ksp.incremental.logfalse⑥ 迁移路线图分阶段推进风险可控升级 Kotlin 到 2.0先决条件确保 Kotlin 版本 ≥ 2.0AGP 版本 ≥ 8.0K2 编译器默认生效新增 KSP 插件先并行运行同时保留 KAPT只对 1-2 个影响小的库如 Moshi试迁移验证构建产物迁移核心库Room → Hilt → 其余按影响范围由小到大每步都做完整回归测试。注意 Room schema 路径配置变更彻底移除 KAPT 插件所有处理器迁移完成后从 plugins{} 移除kotlin-kapt清理残留 kapt{} 块度量与优化用--scan或 Gradle Build Scan 对比迁移前后的构建时间分布量化收益⑦ 实测迁移后能快多少根据社区和官方数据汇总不同项目差异较大场景KAPTKSP K2提升中型项目全量构建4m 20s2m 45s-37%增量构建改 DAO58s19s-67%CI 流水线时间12m7m 30s-38%增量构建的提升尤其明显——这也是日常开发体验改善最直接的地方。改一个 Room DAO原来等将近一分钟迁移后不到 20 秒每天节省的时间累计起来相当可观。小结KAPT → KSP 这条迁移路径技术上已经非常成熟主流库全部支持迁移成本极低收益明显且可量化。给一个明确的时间判断2026 Q3 是最后的窗口。Kotlin 2.x 后续路线图中KAPT 兼容层已进入维护态不排除在某个大版本中正式移除。到那时你是被动升级踩坑还是主动收益早早验收现在就能决定。配合 K2 编译器改几行配置构建时间可能直接少掉三分之一。这是投入产出比最高的一类工程化升级——不需要重构业务代码不需要评审不需要排期只需要工程师花半天时间跑一遍迁移流程。工程化的价值往往就藏在这些不起眼的工具升级里。你不会记得哪次等构建的 58 秒但那些秒数乘以团队人数、乘以每天构建次数就是每个月实实在在消失的几十个工时。— END —关注公众号持续追踪 Android 大前端工程化