mcpField
C
capacitor-plugin-upgrade-v5-to-v6

capacitor-plugin-upgrade-v5-to-v6

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

关于 capacitor-plugin-upgrade-v5-to-v6

用于将 Capacitor 插件库从 v5 迁移到 v6 的技能，涵盖依赖和原生代码修改、监听器类型调整及可选的 SPM 支持。

主要功能

  1. 01项目快照与版本检查
  2. 02自动迁移命令
  3. 03监听器类型与 iOS 更新
  4. 04可选 SPM 迁移指南
  5. 05构建和迁移验证

适用场景

  1. 01让 v5 插件适配 Capacitor 6 应用
  2. 02更新 addListener 声明和实现
  3. 03在迁移至 v6 时添加 SPM 支持

安装

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

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

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

附带文件metadata.jsonreferences/android.md

详细介绍

Capacitor 插件从 v5 升级到 v6

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

适用场景

  • 快照显示 @capacitor/core 为 5.x，且插件必须能在 Capacitor 6 应用中正常运行。
  • definitions.ts 仍声明 Promise<PluginListenerHandle> & PluginListenerHandle。
  • 用户希望在升级到 6 的同时添加 SPM 支持。

请勿用于：

  • 升级应用 → capacitor-app-upgrade-v5-to-v6。
  • 插件使用 4.x → 请先使用 capacitor-plugin-upgrade-v4-to-v5；使用 6.x → 使用 capacitor-plugin-upgrade-v6-to-v7。跨多个版本升级 → capacitor-plugin-upgrades。
  • 完整的 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手动应用 Gradle 或 Kotlin 更改时

升级前检查

工具最低版本
Node.js18+
Xcode15.0+
Java17
AGP / Gradle8.2.1 / 8.2.1
Android SDK 默认值compileSdk 34，targetSdk 34，minSdk 22
iOS 部署目标13.0（不变）

操作步骤

  1. 确认版本为 5.x 且工作树干净。

  2. 在插件根目录执行：

    npx @capacitor/plugin-migration-v5-to-v6@latest

    检查 git diff。

  3. 手动完成（references/android.md）：将开发依赖更新为 latest-6，将 peer @capacitor/core 更新为 ^6.0.0，将 compileSdk（不是 compileSdkVersion）默认值设为 34，将 targetSdkVersion 默认值设为 34，将 AGP 更新为 8.2.1，将 Gradle 更新为 8.2.1，将 Kotlin 更新为 1.9.10。

  4. definitions.ts：每个 addListener 重载都必须只返回 Promise<PluginListenerHandle>：

      addListener(
    eventName: 'resume',
    listenerFunc: () => void,
- ): Promise<PluginListenerHandle> & PluginListenerHandle;
+ ): Promise<PluginListenerHandle>;

    同步更新 web.ts 和 README/docgen 输出。对于使用同步句柄的使用者而言，这是一个破坏性变更。

  5. iOS：从插件 .m 文件中删除 CAP_PLUGIN_METHOD(removeAllListeners, CAPPluginReturnPromise);。现在所有插件都内置此方法。

  6. 可选 SPM：Capacitor 6 添加了实验性的 SPM 支持。询问用户是否要现在添加；如果要，请遵循 capacitor-plugin-spm-support（添加 Package.swift，并在 Swift 中遵循 CAPBridgedPlugin）。

  7. 使用 capacitor-app-upgrade-v5-to-v6 升级示例应用，将插件主版本号递增，并注明“需要 Capacitor 6”。

验证

grep -n "\"@capacitor/" package.json                               # 6.x
grep -rn "& PluginListenerHandle" src/                             # expect none
grep -rn "removeAllListeners" ios/ --include=*.m 2>/dev/null       # expect none
grep -n "compileSdkVersion project\|gradle:8.2.1" android/build.gradle   # compileSdk + 8.2.1
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.2.1
npm run build
npm run verify        # if the repo has the template verify scripts

在两个平台上运行示例应用；逐一添加和移除每个监听器。

错误处理

错误修复方法
示例/测试中 TS 报错：Property 'remove' does not exist on type 'Promise<PluginListenerHandle>'对 addListener 调用使用 await。
AGP 针对 compileSdkVersion 发出弃用警告使用 compileSdk。
.m 文件中仍列出 removeAllListeners删除 CAP_PLUGIN_METHOD 行（步骤 5）；此方法已内置。
示例应用因 @capacitor/core 出现 ERESOLVEpeer 版本范围仍为 ^5；将其设为 ^6.0.0。

评论

支持 Markdown