Gradle 8.0+ 中启用 KSP 插件必须显式声明 version 并设 apply false，模块级需同时启用 Kotlin 和 KSP 插件且顺序正确，AGP ≥ 8.4，KSP 与 Kotlin、AGP 版本须严格匹配。
Gradle 8.0+ 中启用 KSP 插件必须声明 version 并 apply false
Gradle 8.0 起插件应用策略收紧，id("com.google.devtools.ksp") 不能直接 apply true 在根项目中，否则会报 Plugin with id 'com.google.devtools.ksp' not found 或版本冲突。必须在 gradle/libs.versions.toml 或根 build.gradle.kts 的 pluginManagement 块里显式声明版本，并设为 apply false。
当前（2026年10月）稳定兼容的组合是：kotlin 版本 2.3.20 对应 ksp 版本 2.3.20-1.0.29（注意后缀不是随机的，1.0.29 是 KSP 自身迭代号）。你可以在 KSP GitHub Releases 页面确认最新匹配对。
- 在
gradle/libs.versions.toml中添加：[versions] ksp = "2.3.20-1.0.29" kotlin = "2.3.20" [plugins] ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" } - 或在根
build.gradle.kts的pluginManagement中硬编码：pluginManagement { repositories { mavenCentral() gradlePluginPortal() maven { setUrl("https://maven.aliyun.com/repository/gradle-plugin") } } plugins { id("com.google.devtools.ksp") version "2.3.20-1.0.29" apply false } }
模块级 build.gradle.kts 必须同时启用 KSP 和 Kotlin 插件
KSP 不是独立构建阶段，它依赖 Kotlin 编译器前端输出的符号信息。如果只加 id("com.google.devtools.ksp") 而没启用 org.jetbrains.kotlin.android（或 kotlin.jvm），KSP 会静默跳过处理，不报错也不生成代码——这是最常被忽略的“假成功”场景。
- 模块级配置必须包含两者：
plugins { alias(libs.plugins.android.application) // or android.library alias(libs.plugins.kotlin.android) alias(libs.plugins.ksp) // ← 这行不能少，且必须在 kotlin 插件之后（顺序敏感） } - 若用传统写法（非 Version Catalog），确保：
plugins { id("com.android.application") id("org.jetbrains.kotlin.android") id("com.google.devtools.ksp") } - Android Gradle Plugin（AGP）版本需 ≥ 8.4，否则
ksp插件可能无法识别androidx.room:room-compiler等工件中的 KSP 处理器入口。
ksp() 依赖写法和 kapt() 不能共存于同一模块
一个模块里同时存在 kapt 和 ksp 依赖时，Gradle 仍会为所有 Kotlin 源文件生成 Java stub，KSP 的性能优势完全失效。迁移必须彻底——要么全 KSP，要么保留 kapt 但放弃提速。
- Room 示例（正确）：
dependencies { implementation(libs.androidx.room.runtime) implementation(libs.androidx.room.ktx) ksp(libs.androidx.room.compiler) // ← 不是 annotationProcessor，也不是 kapt } - 错误写法（会导致 stub 生成）：
dependencies { kapt(libs.androidx.room.compiler) // ❌ 即使只留这一行，也会触发 stub ksp(libs.androidx.room.compiler) // ❌ 二者并存 = 白配 } - 第三方库如
moshi、dagger-hilt需换用 KSP 专用坐标，例如com.squareup.moshi:moshi-kotlin-codegen已废弃，应改用com.squareup.moshi:moshi-kotlin+ksp(...)。
同步失败时优先检查 Kotlin / KSP / AGP 三者版本锁死关系
Gradle 同步卡住、报 java.lang.NoClassDefFoundError: com/google/devtools/ksp/symbol/KSAnnotated 或 Could not resolve all files for configuration ':app:kspClasspath'，90% 是版本链断裂。KSP API 是二进制不兼容的，symbol-processing-api:2.3.20-1.0.29 只能被 kotlin-compiler-embeddable:2.3.20 加载。
- 验证方式：运行
./gradlew --version确认 Gradle 版本 ≥ 8.7；再检查libs.versions.toml中kotlin、ksp、agp三者是否来自同一发布周期（官方推荐配对表见 KSP Compatibility Matrix）。 - 常见断裂点：
-
agp = "8.7.0"+kotlin = "2.3.20"+ksp = "2.3.20-1.0.28"✅ -
agp = "8.6.0"+kotlin = "2.3.20"+ksp = "2.3.20-1.0.29"❌（1.0.29 需要 AGP 8.7+）
-
- 阿里云镜像必须覆盖
pluginManagement.repositories和dependencyResolutionManagement.repositories两处，缺一不可，否则 KSP 的symbol-processing-api依赖可能拉取失败。
真正卡住的地方往往不是语法，而是三个版本数字没对齐——建议把 kotlin、ksp、agp 的版本号贴在 IDE 侧边栏便签上，每次升级前先查兼容矩阵。
