mcpField
C
capacitor-app-upgrades

capacitor-app-upgrades

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

关于 capacitor-app-upgrades

用于规划和执行 Capacitor 应用升级的路由技能，要求每次只跨一个主版本。它帮助开发者选择目标版本、调用对应版本指南，并在继续前验证每一步升级。

主要功能

  1. 01检测当前 Capacitor 版本
  2. 02规划逐步跨主版本升级
  3. 03转入对应版本的技能
  4. 04检查插件兼容性
  5. 05提供构建和设备验证步骤

适用场景

  1. 01规划跨多个 Capacitor 版本升级
  2. 02在稳定版与预发布版间选择目标
  3. 03继续完成中断的迁移
  4. 04诊断升级后的构建失败

安装

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

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

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

附带文件metadata.json

详细介绍

Capacitor 应用升级（路由器）

规划并逐步执行 Capacitor 应用升级，每一步都使用对应版本的技能。

使用时机

在以下情况触发：

  • 用户想升级 Capacitor 应用，但起始版本或目标版本未知，或两者相差超过一个主版本
  • 用户询问“最新的 Capacitor”（与用户确认选择稳定版 8.5.x 还是预发布版 9）
  • Capacitor 8.4 或更早版本的应用在 Xcode 27 上构建失败（需要执行 8.5 的 UIScene 步骤）
  • npx cap migrate 中途失败，用户需要了解当前进度

请勿用于：

  • 插件库仓库 → capacitor-plugin-upgrades
  • Cordova/PhoneGap 应用 → cordova-to-capacitor
  • 仅从 CocoaPods 迁移到 SPM → cocoapods-to-spm

实时项目快照

package.json 中的当前 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=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

原生平台和 Capacitor 配置路径： !find . -maxdepth 3 \( -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './ios' -o -path './android' \)

版本路径图（2026 年 10 月）

路径技能完成此步骤后的关键要求
4 -> 5capacitor-app-upgrade-v4-to-v5参见技能
5 -> 6capacitor-app-upgrade-v5-to-v6参见技能
6 -> 7capacitor-app-upgrade-v6-to-v7参见技能
7 -> 8capacitor-app-upgrade-v7-to-v8Node 22、Xcode 26、iOS 15、minSdk 24、SDK 36、AGP 8.13、Gradle 8.14.3
8.x -> 8.5capacitor-uiscene-migrationiOS UIScene 生命周期（SceneDelegate + 场景清单）；Xcode 27 要求此步骤
8.5 -> 9capacitor-app-upgrade-v8-to-v9Node 24、Xcode 27、iOS 16、minSdk 26、SDK 37、AGP 9.2.1、Gradle 9.5.1

Capacitor 当前稳定版为 8.5.x（latest）。Capacitor 9 是 next 标签下的预发布版（9.0.0-alpha.x）：在 9.0.0 正式发布前，使用 @next 安装，正式发布后使用 @latest。将生产应用升级到预发布版前，请先征求用户同意；8.5 是稳妥的停止点，且已支持在 Xcode 27 上构建。

流程

  1. 检测。 从快照读取 @capacitor/core（版本范围不明确时运行 npm ls @capacitor/core）。对于 8.x，还要检查是否已采用 UIScene：grep -c UIApplicationSceneManifest ios/App/App/Info.plist。
  2. 与用户确定目标版本（如果用户未说明）：稳定版（8.5.x）或预发布版（9）。
  3. 规划升级路径。 每次只升一个主版本，绝不跳过。从 8.0-8.4 升到 9 时，先插入 8.5 UIScene 步骤。示例：
    • 6 -> 9：6->7、7->8、8->8.5（UIScene）、8.5->9
    • 8.2 -> 9：8.2->8.5（UIScene）、8.5->9
    • 8.5 但没有场景清单 -> 9：先运行 capacitor-uiscene-migration 对于大型应用，将升级路径列为 TODO 清单，并与用户确认。
  4. 逐步升级： 确保 git 工作树干净，加载对应步骤的技能，为目标版本安装 CLI（npm i -D @capacitor/cli@<major>；升级到 9 时使用 @next），运行 npx cap migrate，完成手动检查清单，运行 npx cap sync，然后构建 iOS 和 Android。在两个平台都构建成功前，不要开始下一步。建议每一步提交一次，以便通过二分法定位失败。
  5. 插件。 每一步完成后，将官方 @capacitor/* 插件对齐到相同主版本，并检查第三方及 @capgo/* 插件的 peer 范围（npm view <pkg> peerDependencies）。
  6. 最终验证（见下文），然后提供后续选项：cocoapods-to-spm（预计 CocoaPods Trunk 将于 2026 年 12 月 2 日改为只读），以及按原生版本配置 Capgo 实时更新频道。

验证

npx cap doctor
npm run build && npx cap sync
cd android && ./gradlew assembleDebug && cd ..
xcodebuild -project ios/App/App.xcodeproj -scheme App -destination 'generic/platform=iOS Simulator' build   # CocoaPods: -workspace ios/App/App.xcworkspace
npx cap run ios
npx cap run android

在设备上：启动应用，测试 pause/resume、冷启动和热启动深层链接、推送注册，以及每个原生插件至少调用一次。如果应用通过 OTA 更新发布（Capgo），新原生版本需要新的原生构建；绝不要将为 v9 构建的 bundle 发给 v8 二进制文件（参见 capgo-live-updates）。

错误处理

  • cap migrate 中途停止 → 按照相应版本的技能手动完成升级；不要开始下一个大版本。
  • Migrate can only be used on Capacitor 7 → 已安装的 CLI 版本高于项目使用的版本；先降级 CLI，再进行升级。
  • UIScene migration: project is in a partial state → 由 capacitor-uiscene-migration 处理。
  • 升级后 iOS 构建失败 → 根据版本映射检查部署目标和 Xcode 版本。
  • Android 构建失败 → 根据相应版本的技能检查 AGP、Gradle wrapper、JDK 和 variables.gradle。
  • 第三方插件阻碍升级 → 升级该插件、替换它（在 capacitor-plugins 中查找等效的 Capgo 插件），或暂停在当前版本。

评论

支持 Markdown