mcpField
C
capacitor-plugin-upgrade-v7-to-v8

capacitor-plugin-upgrade-v7-to-v8

github.com/cap-go开发73650 次安装2 周前更新
代码仓库

关于 capacitor-plugin-upgrade-v7-to-v8

为需要将 Capacitor 插件从 7.x 迁移到 8 的维护者提供操作指南，涵盖 Android、iOS、依赖更新及验证步骤。

主要功能

  1. 01运行插件迁移命令
  2. 02更新 Capacitor 依赖版本
  3. 03调整 Android 构建配置
  4. 04调整 iOS 部署配置
  5. 05检查迁移结果并运行示例应用

适用场景

  1. 01让基于 Capacitor 7 的插件支持 Capacitor 8
  2. 02处理 Kotlin 2.2 与 Gradle 配置变更
  3. 03升级插件的 Android 和 iOS 原生项目

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-plugin-upgrade-v7-to-v8

安装后在 Claude Code 中输入/capacitor-plugin-upgrade-v7-to-v8确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
references/
android.md
ios.md

详细介绍

Capacitor 插件升级：从 v7 到 v8

将插件库升级到 Capacitor 8。权威来源：https://capacitorjs.com/docs/updating/plugins/8-0

适用情况

  • 快照显示 @capacitor/core 为 7.x，且插件必须能够在 Capacitor 8 应用中运行。
  • 基于 Kotlin 2.2 构建插件时，在 kotlinOptions 或 kotlin-android-extensions 处失败。
  • Gradle 警告：Properties should be assigned using the 'propName = value' syntax。

请勿用于：

  • 升级应用 → capacitor-app-upgrade-v7-to-v8。
  • 插件为 6.x → 先使用 capacitor-plugin-upgrade-v6-to-v7。跨多个版本升级 → capacitor-plugin-upgrades。
  • 插件已为 8.x → capacitor-plugin-upgrade-v8-to-v9。
  • 添加 SPM → capacitor-plugin-spm-support。

当前项目快照

插件和 Capacitor 包快照： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

示例和原生项目路径： !find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' \)

参考资料

文件适用情况
references/android.md依赖默认值、SDK、AGP/Gradle、= 语法、Java 21、Kotlin 2.2 变更
references/ios.mdpodspec / Package.swift / 旧结构项目中的 iOS 15、capacitor-swift-pm 8

升级前检查

工具最低要求
Node.js22+
Xcode26.0+
iOS 部署目标15.0
Java推荐 21（AGP 8.13 支持 17+）
AGP / Gradle8.13.0 / 8.14.3
Android SDK 默认值minSdk 24、compileSdk 36、targetSdk 36
Kotlin（如使用）2.2.20

流程

  1. 确认版本为 7.x，且工作区干净。

  2. 在插件根目录执行：

    npx @capacitor/plugin-migration-v7-to-v8@latest

    检查 git diff。

  3. package.json：将开发依赖 @capacitor/cli、core、android、ios 升级到 ^8.0.0；将对等依赖 @capacitor/core 升级到 >=8.0.0。

  4. Android 按照 references/android.md 操作：

    • 仅添加或更新插件实际使用的 ext {} 依赖默认值。
    • SDK 默认值设为 24/36/36，AGP 设为 8.13.0，Gradle 设为 8.14.3，google-services 设为 4.4.4（如使用）。
    • 将每个属性赋值都改为 =（namespace = ...、compileSdk = ...、url = ...、abortOnError = ...）。mavenCentral() 等方法调用保持不变。
    • 在 compileOptions 中使用 Java 21。
    • Kotlin 插件：kotlin_version 设为 2.2.20，将 kotlinOptions {} 替换为 kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }，移除 kotlin-android-extensions（改用 kotlin-parcelize / view binding）。
    • 引用 R.layout.bridge_layout_main 的代码必须改用 capacitor_bridge_layout_main。

  5. iOS 按照 references/ios.md 操作：podspec 设为 15.0，Package.swift 设为 .iOS(.v15)，capacitor-swift-pm 设为 from: "8.0.0"。如果插件曾自行发布 .capacitorViewDidAppear / .capacitorViewWillTransition，请移除相关代码；这些事件由 Capacitor 8 发出。

  6. 使用 capacitor-app-upgrade-v7-to-v8 升级示例应用，将插件主版本号升一级，并注明“需要 Capacitor 8”。

升级到 8.x 后：后续步骤

  • Capacitor 8.5 应用将采用 iOS UIScene 生命周期（Xcode 27 要求）。如果插件挂接了 AppDelegate 方法（application(_:open:options:)、continue userActivity、applicationDidBecomeActive 等），或使用 UIApplication.shared.windows / keyWindow，则必须支持基于 scene 的应用；请参阅 capacitor-uiscene-migration。
  • 接着使用 capacitor-plugin-upgrade-v8-to-v9（Capacitor 9 目前位于 next，尚未正式发布）。

验证

grep -n "\"@capacitor/" package.json                                    # ^8.0.0 / >=8.0.0
grep -nE "^\s*(namespace|compileSdk|url|abortOnError|minSdkVersion|targetSdkVersion) [^=]" android/build.gradle   # expect none
grep -n "kotlinOptions\|kotlin-android-extensions" android/build.gradle # expect none
grep -n "VERSION_21\|gradle:8.13.0" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.14.3
grep -rn "bridge_layout_main" android/src | grep -v capacitor_bridge   # expect none
grep -n "deployment_target" *.podspec                                  # '15.0'
grep -n "iOS(\|capacitor-swift-pm" Package.swift 2>/dev/null           # .v15, from: "8.0.0"
npm run build
npm run verify         # if the repo has the template verify scripts
cd android && ./gradlew build --warning-mode all

在两个平台上运行示例应用。

错误处理

错误修复方法
Properties should be assigned using the 'propName = value' syntax在属性赋值中添加 =。
Kotlin：在 Kotlin 2.2 下，kotlinOptions 已弃用／报错使用 kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }，并添加 import org.jetbrains.kotlin.gradle.dsl.JvmTarget。
Plugin [id: 'kotlin-android-extensions'] was not found移除它；改用 kotlin-parcelize 和视图绑定。
Inconsistent JVM-target compatibility detected for tasks将 Java compileOptions 和 Kotlin jvmTarget 设为相同版本（21）。
R.layout.bridge_layout_main 上出现 cannot find symbol使用 capacitor_bridge_layout_main。
SPM 解析选择了 Capacitor 7将 capacitor-swift-pm 设为 from: "8.0.0"。

评论

支持 Markdown