如何将 Capacitor 插件升级到 Capacitor 8

若要将 Capacitor 插件升级到 Capacitor 8，请运行 bunx @capacitor/plugin-migration-v7-to-v8@latest 在插件根目录下执行，然后检查差异：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. 最后在两个平台上构建示例 App 并发布新的大版本。

本指南面向插件维护者。App 开发团队应遵循 如何将您的 Capacitor App 升级至 Capacitor 8.

插件作者需要注意的变化

本地及 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/docgenRollup、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.
• Regenerates the Gradle wrapper with ./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，请在迁移后运行格式化和 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 部署目标 (deployment target)

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 pins capacitor-swift-pm 到确切的版本 @capacitor/ios 即已安装的应用版本，而使用范围（range）则允许 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。

选择哪种方案

在绝大多数情况下，请优先使用该工具。其日志会准确告知您剩余步骤。

发布前请务必验证

1. bun install && bun run build (或者您的 verify 脚本)。
2. Android: cd android && ./gradlew clean build test。请使用 JDK 21 进行 Build。
3. 使用 CocoaPods 的 iOS: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (新的布局插件使用 xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. 使用 SPM 的 iOS: swift package resolve，然后构建 Scheme。
5. 在全新的 Capacitor 8 应用中安装插件 (bunx cap add ios 默认提供 SPM 支持，也适用于 CocoaPods 应用。请在真机上调用所有公开方法。
6. 运行 bunx cap doctor 在测试应用中。

发布

• 升级到新的大版本（该工具使用 8.0.0）。提高 minSdk 和 iOS 最低版本要求对使用者来说属于破坏性变更。
• 编写简短的 BREAKING.md 或更新日志：例如新的 peer 范围、minSdk 24、iOS 15、构建所需的 Java 21，以及任何 API 的行为变更。
• 保留一个 7.x 分支，如果你仍需为 Capacitor 7 用户提供修复，并将其发布到类似 latest-7.
• 的 dist-tag 下。

Capgo 在此周期内维护着大量的插件，其中每个 @capgo/* 重大版本变更意味着 Capacitor 的重大更新。你可以在 插件目录中查看.

故障排除

invalid source release: 21. Gradle 正在 JDK 17 或更低版本上运行。请使用 Android Studio Otter 附带的 JDK 21，并在 JAVA_HOME 中进行设置。

Unsupported class file major version 65. 相反的问题：你使用了 JDK 21，但 Gradle wrapper 版本过旧，无法读取 Java 21 的 class 文件。请使用 8.14.3 版本重新生成 wrapper。

Namespace not specified. AGP 8+ 需要 namespace = "..." 在插件的 android 块中。旧版插件仅在 package 中包含 AndroidManifest.xml属性。请将其移至 Gradle 并从 package 中移除。

'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 以便您的插件也能在这些应用中构建。详情请参阅 修复使用 AGP 9 时 Capacitor 插件的构建错误.

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 用户。