KMP 项目升级到 AGP 9.0 时如何迁移插件…

当 Kotlin Multiplatform 项目因 Android Gradle Plugin 9.0 与 KMP 插件不兼容而构建失败，或需要主动升级到 AGP 9.0 时使用。

适用场景

解决思路

1. 先分析项目结构：读取 settings.gradle.kts 找出所有模块；逐个读取模块的 build.gradle.kts 确认应用的插件；检查是否存在 gradle/libs.versions.toml 版本目录（存在则从中读取 AGP/Gradle/Kotlin 版本，不存在则从根 build.gradle.kts 的 buildscript{} 或 plugins{} 中读取），并据此调整示例写法（版本目录用 alias(libs.plugins.xxx)，直接声明用 id("plugin.id") version "x.y.z"）；读取 gradle/wrapper/gradle-wrapper.properties 获取 Gradle 版本；检查 gradle.properties 中已有的临时规避属性（如 android.enableLegacyVariantApi）；检查是否使用了 org.jetbrains.kotlin.android 插件（AGP 9.0 内置 Kotlin，必须移除）；检查是否使用了 org.jetbrains.kotlin.kapt 插件（与内置 Kotlin 不兼容，需迁移到 KSP 或 com.android.legacy-kapt）；检查第三方插件是否与 AGP 9.0 兼容。若可用 Bash，运行技能目录下的 scripts/analyze-project.sh 获取结构化摘要。
2. 按模块分类迁移路径：kotlin.multiplatform + com.android.library 走 Path A（库插件替换）；kotlin.multiplatform + com.android.application 走 Path B（强制拆分 Android 模块）；单模块内含多个平台入口走 Path C（推荐全面重构）；纯 Android 模块参考 Pure Android Tips。Path B 对 KMP+application 组合是强制的；Path C 在存在单体 composeApp 模块时推荐；需询问用户只做 Path B 还是做 Path C。
3. Path A（库模块迁移）：1) 将 com.android.library 替换为 com.android.kotlin.multiplatform.library；2) 移除 org.jetbrains.kotlin.android 插件；3) 把顶层 android{} 配置移入 kotlin { android { ... } }，例如 namespace、compileSdk、minSdk；4) 若使用经典 Android 目录布局则重命名源码目录：src/main→src/androidMain、src/test→src/androidHostTest、src/androidTest→src/androidDeviceTest（已是 androidMain 布局则无需改）；5) 把顶层 dependencies{} 移入 sourceSets，例如 kotlin { sourceSets { androidMain.dependencies { implementation("androidx.appcompat:appcompat:1.7.0") } } }；6) 若使用 Android 或 Compose Multiplatform 资源，显式启用 kotlin { android { androidResources { enable = true } } }；7) 若含 .java 源文件，启用 kotlin { android { withJava() } }；8) 若有单元/仪器测试，显式启用 withHostTest { isIncludeAndroidResources = true } 和 withDeviceTest { instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" }；9) 更新 Compose 工具依赖：debugImplementation(libs.androidx.compose.ui.tooling) 改为 androidRuntimeClasspath(libs.androidx.compose.ui.tooling)；10) 如需发布 consumer ProGuard 规则，显式配置 kotlin { android { consumerProguardFiles.add(file("consumer-rules.pro")) } }；11) 处理子依赖变体（产品风味/构建类型）：新插件为单变体架构，需用 localDependencySelection 配置回退，例如 selectBuildTypeFrom.set(listOf("debug", "release"))，以及 productFlavorDimension("tier") { selectFrom.set(listOf("free")) }。
4. Path B（Android 应用 + 共享模块拆分，强制）：1) 新建 androidApp 模块及其 build.gradle.kts，应用 androidApplication 插件（不要应用 kotlin-android，AGP 9.0 已内置 Kotlin），如用 Compose 则加 composeMultiplatform 和 composeCompiler 插件，配置 android { namespace、compileSdk、defaultConfig{applicationId、minSdk、targetSdk、versionCode、versionName}、buildFeatures { compose = true } }，依赖 implementation(projects.shared) 和 implementation(libs.androidx.activity.compose)；2) 把 Android 入口代码从 src/androidMain/ 移到 androidApp/src/main/：MainActivity.kt 及其他 Activity/Fragment、应用级 AndroidManifest.xml（含 <application> 和 launcher <activity>，确认 <activity> 的 android:name 使用新位置的完全限定类名）、Application 类、应用级资源（启动图标、主题等）；3) 在 settings.gradle.kts 中加入 include(":androidApp")；4) 在根 build.gradle.kts 中加入插件声明并 apply false；5) 用 Path A 步骤把原模块从 application 转为 library；6) 确保 app 模块与 library 模块使用不同 namespace；7) 从共享模块移除 applicationId、targetSdk、versionCode、versionName；8) 更新 IDE 运行配置，把模块从旧模块改为 androidApp。
5. Path C（推荐全面重构）：目标结构为 shared/（原 composeApp，纯共享代码）、androidApp/、desktopApp/、webApp/、iosApp/ 等。步骤：1) 先执行 Path B 抽出 androidApp；2) 若有 desktop 目标，抽出 desktopApp：新建模块并应用 org.jetbrains.compose 和 application{} 插件，把 main() 从 desktopMain 移到 desktopApp/src/main/kotlin/，把 compose.desktop { application { ... } } 配置移到 desktopApp/build.gradle.kts，添加对 shared 的依赖；3) 若有 wasmJs/js 目标，抽出 webApp：新建模块并配置 Kotlin/JS 或 Kotlin/Wasm，把 Web 入口从 wasmJsMain/jsMain 移到 webApp/src/wasmJsMain/kotlin/，把浏览器/分发配置移到 webApp/build.gradle.kts，添加对 shared 的依赖；4) iOS 通常已在独立 iosApp 目录，确认框架导出配置（binaries.framework）留在 shared 模块，Xcode 工程引用正确的框架路径；5) 把模块从 composeApp 重命名为 shared：重命名目录、更新 settings.gradle.kts 的 include、更新所有模块的依赖引用；6) 清理 shared 模块，移除已迁出的平台入口代码和应用专属配置。变体：若部分平台用原生 UI（如 iOS 用 SwiftUI），把 shared 拆为 sharedLogic（所有平台共用的业务逻辑）和 sharedUI（仅共享 UI 平台使用的 Compose Multiplatform UI）；若含 server 目标，在根目录加 server 模块，把所有客户端模块移到 app/ 目录下，并加 core 模块存放服务端与客户端共享的代码（模型、校验）。
6. 版本更新（所有迁移路径都必须做）：1) Gradle wrapper 升级到 9.1.0+，修改 gradle/wrapper/gradle-wrapper.properties 中 distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip；2) AGP 升级到 9.0.0+ 并加入 KMP library 插件：有版本目录时在 [versions] 加 agp = "9.0.1"，在 [plugins] 加 android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }；无版本目录时更新 com.android.* 插件版本并在根 build.gradle.kts 加 id("com.android.application") version "9.0.1" apply false 和 id("com.android.kotlin.multiplatform.library") version "9.0.1" apply false；3) 确保使用 JDK 17+（AGP 9.0 要求）；4) SDK Build Tools 升级到 36.0.0（通过 SDK Manager 安装或配置 android { buildToolsVersion = "36.0.0" }）；5) 检查 gradle.properties，移除会报错的属性并审查变更的默认值。
7. 内置 Kotlin 迁移（AGP 9.0 默认对所有 com.android.application 和 com.android.library 模块启用内置 Kotlin，org.jetbrains.kotlin.android 插件不再需要且会冲突；注意内置 Kotlin 不替代 KMP 支持，KMP 库模块仍需 org.jetbrains.kotlin.multiplatform + com.android.kotlin.multiplatform.library）：1) 从所有模块级和根级构建文件中移除 kotlin-android 插件，并从版本目录删除对应条目；2) 迁移 kapt：org.jetbrains.kotlin.kapt 与内置 Kotlin 不兼容，优先迁移到 KSP（参考各注解处理器的 KSP 迁移指南），回退方案是使用 com.android.legacy-kapt（版本与 AGP 相同），在版本目录加 legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "agp" }，模块中把 kotlin-kapt 替换为 legacy-kapt；3) 把纯 Android 模块的 android.kotlinOptions{} 迁移到顶层 kotlin.compilerOptions{}，例如 jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)、languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)、optIn.add("kotlin.RequiresOptIn")（内置 Kotlin 下 jvmTarget 默认取 android.compileOptions.targetCompatibility，若已设 compileOptions 可省略）；4) 把 kotlin.sourceSets 迁移到 android.sourceSets：不支持 kotlin.sourceSets.named("main") { kotlin.srcDir(...) }，应改为 android.sourceSets.named("main") { kotlin.directories += "additionalSourceDirectory/kotlin" }；生成源码用 Variant API：androidComponents.onVariants { variant -> variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin") }。
8. 大型项目按模块逐步迁移：1) 在 gradle.properties 全局禁用 android.builtInKotlin=false；2) 对已迁移模块应用 opt-in 插件 id("com.android.built-in-kotlin") version "AGP_VERSION"；3) 对该模块执行上述 1-4 步；4) 全部迁移完成后移除 android.builtInKotlin=false 和所有 com.android.built-in-kotlin 插件。对不含 Kotlin 源码的模块可设 android { enableKotlin = false } 以节省构建时间。若被插件不兼容阻塞，可临时在 gradle.properties 设 android.builtInKotlin=false 和 android.newDsl=false 退出，但需询问用户并提醒这是临时措施。
9. 迁移前盘点所有插件并对照 references/PLUGIN-COMPATIBILITY.md 的兼容性表检查；若有插件无可用规避方案，告知用户；若插件需要 opt-out 标志，加入 gradle.properties 并标注为临时规避。
10. 检查 gradle.properties 中 AGP 9.0 变更的默认值并处理冲突：android.uniquePackageNames 由 false 变 true（确保每个库有唯一 namespace）；android.enableAppCompileTimeRClass 由 false 变 true（把对 R 字段的 switch 重构为 if/else）；android.defaults.buildfeatures.resvalues 由 true 变 false（需要处启用 resValues = true）；android.defaults.buildfeatures.shaders 由 true 变 false（需要处启用 shaders）；android.r8.optimizedResourceShrinking 由 false 变 true（审查 R8 keep 规则）；android.r8.strictFullModeForKeepRules 由 false 变 true（keep 规则要显式）；android.proguard.failOnMissingFiles 由 false 变 true（移除无效的 ProGuard 文件引用）；android.r8.proguardAndroidTxt.disallowed 由 false 变 true（只用 proguard-android-optimize.txt）；android.r8.globalOptionsInConsumerRules.disallowed 由 false 变 true（从库 consumer 规则中移除全局选项）；android.sourceset.disallowProvider 由 false 变 true（改用 androidComponents 上的 Sources API）；android.sdk.defaultTargetSdkToCompileSdkIfUnset 由 false 变 true（显式指定 targetSdk）；android.onlyEnableUnitTestForTheTestedBuildType 由 false 变 true（仅在测试非默认构建类型时关注）。同时移除已报错的属性：android.r8.integratedResourceShrinking（已移除，始终开启）、android.enableNewResourceShrinker.preciseShrinking（已移除，始终开启）。
11. 纯 Android 模块升级：先按内置 Kotlin 迁移步骤处理，再审查 Gradle 属性默认值变更表；额外注意 BaseExtension 已移除，改用 CommonExtension 或具体扩展类型；Java 默认从 Java 8 变为 Java 11，确保 compileOptions 反映此变化。
12. 迁移后验证：1) ./gradlew build 无错误通过；2) 所有平台目标构建成功（Android、iOS 用 xcodebuild、Desktop、JS/Wasm）；3) ./gradlew :shared:allTests 和 Android 单元测试通过；4) KMP 模块中不再有 com.android.library 或 com.android.application；5) AGP 9.0 模块中不再有 org.jetbrains.kotlin.android；6) source set 使用正确名称（androidMain、androidHostTest、androidDeviceTest）；7) 无 variant API 或 DSL 的弃用警告。
13. 常见坑处理：KMP 库插件下 BuildConfig 不可用，改用 DI/AppConfiguration 接口，或用 BuildKonfig、gradle-buildconfig-plugin 生成编译期常量；无构建变体（单变体架构），编译期常量可用 BuildKonfig/gradle-buildconfig-plugin 的 flavor，但变体专属依赖/资源/签名必须移到 app 模块；新插件不支持 NDK/JNI，需抽到独立的 com.android.library 模块；Compose 资源未设 androidResources { enable = true } 会崩溃；consumer ProGuard 规则若未迁移到新 DSL 的 consumerProguardFiles.add(file(...)) 会被静默丢弃；KSP 需 2.3.1+ 才兼容 AGP 9.0；BaseExtension 已移除，使用旧 DSL 类型的约定插件需改用 CommonExtension 重写；Variant API 已移除，applicationVariants、libraryVariants、variantFilter 被 androidComponents 取代；约定插件需重构，旧的 android{} 扩展辅助方法已废弃。

适用边界 · 注意事项

• 项目未使用 Kotlin Multiplatform 或未计划升级到 AGP 9.0 时不适用
• 无法升级 Gradle 到 9.1.0+ 或 JDK 到 17+ 的环境下不适用
• 依赖的第三方插件在兼容性表中标记为无规避方案的损坏状态时，迁移会被阻塞，需先解决插件问题