若要将 Capacitor 插件升级至 Capacitor 8，请运行 bunx @capacitor/plugin-migration-v7-to-v8@latest 在插件根目录下执行，然后检查 diff：Capacitor 依赖升级到 8.x，Android 目标为 SDK 36、minSdk 24，AGP 8.13 和 Gradle 8.14.3，Kotlin 升到 2.2.20，并包含 compilerOptions，iOS 的部署目标提升至 15.0，并 capacitor-swift-pm 8. 最后，在两个平台上构建示例应用并发布新的主版本。
本指南面向插件维护者。应用团队应遵循 如何将您的 Capacitor 应用升级到 Capacitor 8.
插件作者需要关注哪些变更
| 文件 | 变更 |
|---|---|
package.json |
@capacitor/core peer 依赖 >=8.0.0，开发依赖 @capacitor/cli, core, android, ios 改为 ^8.0.0 |
android/build.gradle |
compileSdk = 36, minSdkVersion = 24, targetSdkVersion = 36，AndroidX 版本升级 |
android/build.gradle （buildscript） |
AGP 8.13.0, google-services 4.4.4、Kotlin 2.2.20 |
android/gradle/wrapper/gradle-wrapper.properties |
Gradle 8.14.3 |
| 所有 Gradle 文件 | = 赋值语法， kotlinOptions 替换为 compilerOptions |
*.podspec |
s.ios.deployment_target = '15.0' |
Package.swift |
.iOS(.v15) 以及 capacitor-swift-pm from: "8.0.0" |
本地及 CI 环境所需的平台工具：Node.js 22+、Xcode 26+、Android Studio Otter (2025.2.1) 或更高版本，以及 JDK 21。
方案 1：运行官方迁移工具
在插件根目录下，确保 git 工作区干净：
bunx @capacitor/plugin-migration-v7-to-v8@latest该工具：
- 更新 Capacitor 依赖并将你的 package 版本设置为
8.0.0. - 更新官方模板使用的开发工具：
@capacitor/docgen、Rollup、TypeScript@types/node，以及 Prettier（如果你使用，则从 v2 升级到 v3）@ionic/prettier-config，以及prettier-plugin-java). - 删除
node_modules/@capacitor以及package-lock.json，然后运行npm install。如果你使用 Bun，该步骤会失败并给出警告。运行bun install之后自行运行并提交bun.lock. - 重新生成 Gradle wrapper，使用
./gradlew wrapper --gradle-version 8.14.3. - 重写
build.gradle：SDK 级别、AndroidX 版本、AGP、Kotlin 版本、Java 21 兼容性以及kotlinOptions改为compilerOptions. - 将 podspec 部署目标从 14.0 提升至 15.0，并在
Package.swift中设置.iOS(.v15)以及from: "8.0.0"来实现capacitor-swift-pm.
当预期的字符串缺失时，它会记录 Unable to find "..." in <file>. Try updating it manually。这些行中的每一行都是你需要手动执行的步骤。包含自定义 Gradle 逻辑、非标准文件夹或重命名文件的插件会产生最多的此类日志。
如果 Prettier 从 v2 升级到了 v3，请在迁移后运行 format 和 lint 脚本。格式差异可能很大，建议将其与功能变更分开提交。
选项 2：手动升级
当工具无法解析文件，或希望逐条审查变更时，请使用此方法。步骤遵循 官方插件升级指南.
1. 依赖项
{
"devDependencies": {
"@capacitor/android": "^8.0.0",
"@capacitor/cli": "^8.0.0",
"@capacitor/core": "^8.0.0",
"@capacitor/ios": "^8.0.0"
},
"peerDependencies": {
"@capacitor/core": ">=8.0.0"
}
}2. Android SDK 级别与 Gradle 语法
android {
namespace = "com.example.plugin"
compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
defaultConfig {
minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
}
lintOptions {
abortOnError = false
}
}保留这种 project.hasProperty(...) ? rootProject.ext... : default 模式。它让宿主应用的 variables.gradle 控制这些值，从而避免应用中出现“针对版本 36 编译”这类错误。
本指南中介绍的 = 语法仅适用于属性。像这样的方法调用 mavenCentral() 保持不变，并且 maven { url = "..." } 需要 =.
3. AndroidX 默认配置
只升级插件实际使用的库。Capacitor 8 的默认配置为：
ext {
junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}官方列表中的其他项： androidxCoordinatorLayoutVersion 1.3.0, androidxFragmentVersion 1.8.9, firebaseMessagingVersion 25.0.1, androidxBrowserVersion 1.9.0, androidxMaterialVersion 1.13.0, androidxExifInterfaceVersion 1.4.1, coreSplashScreenVersion 1.2.0.
4. AGP 与 Gradle wrapper
buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:8.13.0'
}
}cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3如果你的插件使用了 Firebase 或其他 Google 服务，请设置 com.google.gms:google-services 改为 4.4.4.
5. Java 21 和 Kotlin 2.2
AGP 8.13 和 SDK 36 推荐使用 Java 21。插件本身仍兼容 Java 17。
compileOptions {
sourceCompatibility = JavaVersion.VERSION_21
targetCompatibility = JavaVersion.VERSION_21
}对于 Kotlin 插件，请更新默认版本并将 jvmTarget 移出 kotlinOptions。Kotlin 2.2 会将旧代码块视为错误：
import org.jetbrains.kotlin.gradle.dsl.JvmTarget
buildscript {
ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
}
android {
// remove: kotlinOptions { jvmTarget = '17' }
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.JVM_21
}
}保留 jvmTarget 以及 targetCompatibility 使用相同的 Java 版本，否则 Gradle 会报“Inconsistent JVM-target compatibility”错误并停止。如果你仍然应用 kotlin-android-extensions，将其移除。使用 kotlin-parcelize 来实现 @Parcelize 以及用于访问合成视图的 view binding。
6. iOS 部署目标
Podspec:
s.ios.deployment_target = '15.0'Package.swift:
platforms: [.iOS(.v15)],
dependencies: [
.package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
],使用 from:，而不是 branch: 或 exact:。应用生成的 CapApp-SPM package 固定 capacitor-swift-pm 到已安装应用的精确版本， @capacitor/ios 而版本范围则让 SPM 根据该版本解析你的插件。
采用旧版 Xcode 项目布局的插件，还需要在项目的 Build Settings 中调高部署目标 以及在 ios/Podfile (platform :ios, '15.0').
如果您的插件还没有 Package.swift ，那就接下来做这一步。使用 Capacitor 8 创建的应用默认使用 SPM，会跳过您的插件并给出“与 SPM 不兼容”的警告。请参考 如何将 Capacitor 插件迁移到 Swift Package Manager.
方案 3：让 Agent 来处理
开源的 Capgo 技能 包括 capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades 用于跨多个版本升级，以及 capacitor-plugin-spm-support。使用以下命令安装 bunx skills add Cap-go/capgo-skills 并让您的 Agent 升级插件。该 Skill 会运行官方工具，然后处理工具日志中标记为跳过的步骤。请像审查队友的 PR 一样审查 diff。
该用哪种方案
| 方案 | 适用场景 | 注意事项 |
|---|---|---|
| 迁移工具 | 基于官方模板生成的插件 | 自定义文件上跳过的步骤， npm install 包含 Bun 的步骤 |
| 手动 | 深度定制的 Gradle 或 Xcode 配置 | 容易漏掉某个 AndroidX 或 Kotlin 变更 |
| Agent + 技能 | 待升级插件多，或布局混杂 | 你仍然掌控审核流程 |
几乎在所有情况下，都从工具开始。它的日志会准确告诉你还剩什么。
发布前先验证
bun install && bun run build（或你的verify脚本）。- Android：
cd android && ./gradlew clean build test。使用 JDK 21 构建。 - 使用 CocoaPods 的 iOS:
cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS(新版布局插件使用xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS). - 使用 SPM 的 iOS:
swift package resolve，然后构建 scheme。 - 在全新的 Capacitor 8 应用中安装插件 (
bunx cap add ios默认提供 SPM）以及在 CocoaPods 应用中。在真机上调用每个 public 方法。 - 运行
bunx cap doctor在测试应用中。
发布
- 升级到新的 major 版本（该工具使用
8.0.0）。提高 minSdk 和 iOS 最低版本对下游用户来说是 breaking change。 - 写一段简短的
BREAKING.md或 changelog 条目：新的 peer 依赖范围、minSdk 24、iOS 15、构建用 Java 21，以及 API 的任何行为变更。 - 保留一个
7.x分支，如果你仍要为 Capacitor 7 用户发布修复，就把这些修复发布到类似以下的 dist-tag 下：latest-7. - 更新 README 的安装部分和兼容性表格。
Capgo 在这一周期维护着一大批插件，每个 @capgo/* major 版本会跟随 Capacitor 的 major 版本。你可以在 插件目录中浏览.
故障排除
invalid source release: 21. Gradle 正在 JDK 17 或更旧版本上运行。请使用 Android Studio Otter 内置的 JDK 21，并在 JAVA_HOME CI 中设置。
Unsupported class file major version 65. 相反的问题：你用的是 JDK 21，但 Gradle wrapper 太旧，无法读取 Java 21 的 class 文件。请用 8.14.3 重新生成 wrapper。
Namespace not specified. AGP 8+ 需要 namespace = "..." 在插件的 android block 中。旧版插件只有 package 属性在 AndroidManifest.xml中。请将其移到 Gradle，并从 package manifest 中移除。
'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). 你的 Kotlin jvmTarget 不匹配 targetCompatibility。请将两者都设为 21 或都设为 17。
提及 proguard-android.txt 在 AGP 9 中的错误。 一些应用已经运行 AGP 9。切换到 proguard-android-optimize.txt 以便你的插件也能在这些应用中构建。详情见 修复 Capacitor 插件在 AGP 9 下的构建错误.
SPM: product 'Capacitor' required by package ... not found. 你的 Package.swift 依赖行存在拼写错误或使用了不存在的版本。请使用 from: "8.0.0" 对比 https://github.com/ionic-team/capacitor-swift-pm.git.
Play Console 中的 16 KB 页面大小警告。 如果您的插件包含原生 .so 库，请使用 16 KB 对齐方式重新构建它们。详见 Android 16 KB 页面大小与 Capacitor 插件.
一旦插件升到 8，下一步就是为 9 做准备。 为 Capacitor 9 做准备 列出了插件团队现在可以做、又不会影响 Capacitor 8 用户的更改。
