mcpField
C
capacitor-plugin-upgrades

capacitor-plugin-upgrades

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

关于 capacitor-plugin-upgrades

为 Capacitor 插件维护者提供版本升级规划技能，按相邻主版本逐步升级，并通过对应版本指南完成迁移和验证。

主要功能

  1. 01检测插件支持的版本范围
  2. 02规划逐个主版本升级
  3. 03使用对应迁移技能
  4. 04检查 API 与原生配置
  5. 05在插件和示例应用中验证

适用场景

  1. 01扩展插件以支持更新的 Capacitor 主版本
  2. 02处理 peerDependencies 落后于应用版本
  3. 03排查插件在新版本或场景化应用中的兼容问题

安装

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

$npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-plugin-upgrades

安装后在 Claude Code 中输入/capacitor-plugin-upgrades确认已加载。

附带文件metadata.json

详细介绍

Capacitor 插件升级（路由器）

规划并执行插件升级，每次提升一个主版本，并在每次升级时使用对应版本的技能。

适用场景

在以下情况下触发：

  • 插件维护者希望支持更新的 Capacitor 主版本，但不清楚需要升级几步
  • peerDependencies["@capacitor/core"] 落后于应用的 Capacitor 版本
  • 插件用户报告它在 Capacitor 8.5 的基于场景的应用或 Capacitor 9 上无法正常运行

请勿用于：

  • 应用项目 -> capacitor-app-upgrades
  • 为插件添加 SPM -> capacitor-plugin-spm-support
  • 将 Cordova 插件转换为 Capacitor 插件 -> cordova-to-capacitor

实时项目快照

插件和 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' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)

版本映射（2026 年 10 月）

跳转技能备注
4 -> 5capacitor-plugin-upgrade-v4-to-v5
5 -> 6capacitor-plugin-upgrade-v5-to-v6
6 -> 7capacitor-plugin-upgrade-v6-to-v7
7 -> 8capacitor-plugin-upgrade-v7-to-v8iOS 15、SDK 36、AGP 8.13
8.5 生命周期capacitor-uiscene-migration（references/plugin-audit.md）仅审计；如果插件遵循单次发布规则，则无需提升版本
8 -> 9capacitor-plugin-upgrade-v8-to-v9npx @capacitor/plugin-migration-v8-to-v9@latest、iOS 16、SDK 37、AGP 9.2.1、API 移除

Capacitor 9 是预发布版本（next 标签，9.0.0-alpha.x）。在 GA 之前使用 next / >=9.0.0-alpha.6 范围；也可以考虑将插件的 v9 版本发布到 npm next 标签下。若要停止支持当前稳定主版本，请先征求用户同意。

流程

  1. 检测支持范围（peer dependency、Package.swift 中的 capacitor-swift-pm 要求、podspec 中的 Capacitor 依赖、android/build.gradle 默认值）。与用户确认目标主版本。
  2. 规划升级步骤，每次提升一个主版本。跨越 8 -> 9 时，在该升级步骤中执行 UIScene 插件审计。例如：7 -> 9 = 7->8、UIScene 审计、8->9。
  3. **每次升级：**确保 git 工作区干净，加载对应升级技能，先运行官方迁移工具（技能指定时使用 npx @capacitor/plugin-migration-v<from>-to-v<to>@latest），检查差异，完成手动检查清单，然后在进行下一次升级前完成验证（第 5 步）。
  4. **每次升级都要重新检查的范围：**TypeScript 定义和导出名称、原生方法签名和负载、Android 命名空间和 Java/Kotlin 工具链、podspec 和 Package.swift 中的 iOS 部署目标（两者都要保留）、README 安装说明和兼容性表。
  5. 验证插件根目录和示例应用。

验证

如果存在 npm run verify，则运行它。否则：

npm run build
npm test --if-present
cd android && ./gradlew clean build && cd ..
xcodebuild -scheme <PluginScheme> -destination 'generic/platform=iOS Simulator' build   # find it with xcodebuild -list
cd example-app && npm install && npx cap sync && npx cap run ios && npx cap run android

从示例/测试应用而非插件根目录运行 npx cap sync 和原生运行。对所有已发布平台上的每个公开方法进行测试。

错误处理

  • 该升级步骤的迁移工具失败或遗漏文件 -> 在进入下一个主版本前，依据对应升级技能手动完成迁移。
  • 示例应用无法运行 -> 发布前修复插件 API 或原生接线。
  • CocoaPods 和 SPM 的使用者都报告问题 -> 检查 podspec 和 Package.swift 是否声明了相同的平台和 Capacitor 范围。
  • 插件仅在基于场景的应用中出问题 -> 可能存在对 AppDelegate 方法或 tmpWindow 的假设；请参阅 capacitor-uiscene-migration。

评论

支持 Markdown