SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场capacitor-plugin-upgrades

capacitor-plugin-upgrades

编程与开发

查看项目

更新于 10-15 14:28

技能介绍

用途

Capacitor Plugin Upgrade 是一个路由型技能，用于规划和执行 Capacitor 插件库的主版本升级，覆盖 4 到 9 的多个主版本。它不直接完成全部升级，而是按“每次只升一个主版本”的方式，为每一跳指向对应的版本专属技能，并在跨越 8 到 9 时把 iOS UIScene 生命周期审计纳入流程。

何时使用

触发条件包括：

  • 插件维护者希望支持更新的 Capacitor 主版本，但不确定需要跨几跳；
  • peerDependencies["@capacitor/core"] 落后于应用所使用的 Capacitor 版本；
  • 插件用户反馈在 Capacitor 8.5 场景化应用或 Capacitor 9 上出现故障。

不适用的情况：

  • 应用项目升级应使用 capacitor-app-upgrades；
  • 为插件添加 SPM 支持应使用 capacitor-plugin-spm-support；
  • Cordova 插件转 Capacitor 插件应使用 cordova-to-capacitor。

版本映射（2026 年 10 月）

技能按跳转提供：

  • 4 -> 5：capacitor-plugin-upgrade-v4-to-v5
  • 5 -> 6：capacitor-plugin-upgrade-v5-to-v6
  • 6 -> 7：capacitor-plugin-upgrade-v6-to-v7
  • 7 -> 8：capacitor-plugin-upgrade-v7-to-v8（iOS 15、SDK 36、AGP 8.13）
  • 8.5 生命周期：capacitor-uiscene-migration（references/plugin-audit.md），仅审计；如果插件遵循 one-release 规则，则无需提升版本号
  • 8 -> 9：capacitor-plugin-upgrade-v8-to-v9，使用 npx @capacitor/plugin-migration-v8-to-v9@latest，涉及 iOS 16、SDK 37、AGP 9.2.1 以及 API 移除

Capacitor 9 目前是预发布版本（next 标签，9.0.0-alpha.x）。在正式发布前应使用 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），审查 diff，完成手动检查清单，然后进行验证（第 5 步），再进入下一跳。
  4. 每一跳都要重新检查的表面范围：TypeScript 定义与导出名称、原生方法签名与载荷、Android namespace 与 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 # 用 xcodebuild -list 查找 scheme 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。

限制

该技能是路由与流程编排，具体每一跳的改动细节由对应的版本专属技能提供。Capacitor 9 为预发布状态，相关版本范围与发布标签需按预发布处理。资料未提供收费、价格或平台支持范围等额外信息。