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

capacitor-app-upgrades

编程与开发

查看项目

更新于 10-15 14:30

技能介绍

用途

Capacitor App Upgrade（router）用于规划和执行 Capacitor 应用的大版本升级，一次只跳一个版本，每一跳使用对应的版本专属技能。

何时使用

触发条件：

  • 用户想升级 Capacitor 应用，但起始版本或目标版本未知，或相隔超过一个大版本
  • 用户要求升级到“最新的 Capacitor”（需与用户一起决定是稳定版 8.5.x 还是预发布版 9）
  • Xcode 27 构建在 Capacitor 8.4 或更旧的应用上失败（需要 8.5 的 UIScene 步骤）
  • npx cap migrate 中途失败，用户需要知道当前处于哪个阶段

不适用：

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

版本映射（2026 年 10 月）

跳跃 技能 跳跃后的关键要求
4 -> 5 capacitor-app-upgrade-v4-to-v5 见该技能
5 -> 6 capacitor-app-upgrade-v5-to-v6 见该技能
6 -> 7 capacitor-app-upgrade-v6-to-v7 见该技能
7 -> 8 capacitor-app-upgrade-v7-to-v8 Node 22、Xcode 26、iOS 15、minSdk 24、SDK 36、AGP 8.13、Gradle 8.14.3
8.x -> 8.5 capacitor-uiscene-migration iOS UIScene 生命周期（SceneDelegate + scene manifest）；Xcode 27 要求
8.5 -> 9 capacitor-app-upgrade-v8-to-v9 Node 24、Xcode 27、iOS 16、minSdk 26、SDK 37、AGP 9.2.1、Gradle 9.5.1

Capacitor 稳定版为 8.5.x（最新）。Capacitor 9 是 next 标签上的预发布版（9.0.0-alpha.x）：在 9.0.0 GA 之前使用 @next 安装，GA 之后使用 @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 无 scene manifest -> 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

在设备上：启动、暂停/恢复、冷启动与热启动深链接、推送注册、每个原生插件调用一次。若应用通过 OTA 更新（Capgo），新的原生版本需要新的原生构建；切勿将针对 v9 构建的 bundle 发送给 v8 二进制（见 capgo-live-updates）。

错误处理

  • cap migrate 中途停止 -> 按该跳技能手动完成，不要开始下一个大版本。
  • Migrate 仅可用于 Capacitor 7 -> 已安装的 CLI 比项目新；先用较旧的 CLI 降级。
  • UIScene 迁移：项目处于部分状态 -> 由 capacitor-uiscene-migration 处理。
  • 某跳后 iOS 构建失败 -> 对照版本映射检查部署目标和 Xcode 版本。
  • Android 构建失败 -> 对照该跳技能检查 AGP、Gradle wrapper、JDK 和 variables.gradle。
  • 第三方插件阻塞某跳 -> 升级它、替换它（在 capacitor-plugins 中查找 Capgo 等价物），或在当前跳暂停。

适用场景与限制

适用于需要跨多个大版本升级 Capacitor 应用、且需要明确升级路径与逐跳验证的开发者。该技能本身是路由型，具体每跳细节依赖对应的版本专属技能。资料未提供收费、价格或平台支持等额外信息。