Gradle在Android项目中怎么配置KSP-java教程-PHP中文网

Gradle 8.0+ 中启用 KSP 插件必须显式声明 version 并设 apply false，模块级需同时启用 Kotlin 和 KSP 插件且顺序正确，AGP ≥ 8.4，KSP 与 Kotlin、AGP 版本须严格匹配。

gradle在android项目中怎么配置ksp

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 但放弃提速。

Android Control

通过命令行工具（uiautomator、screencap、input、am）控制安卓设备。优先尝试非 root 执行，失败后自动回退至 root...

下载

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 侧边栏便签上，每次升级前先查兼容矩阵。