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

capacitor-app-upgrade-v6-to-v7

编程与开发

查看项目

更新于 10-14 21:12

技能介绍

用途

本技能用于把 Capacitor 6 应用迁移到 Capacitor 7。权威依据为 https://capacitorjs.com/docs/updating/7-0。

何时使用

  • package.json 快照中 @capacitor/core 为 6.x，且用户希望升级到 7.x。
  • 升级到 7 后构建失败，出现 JDK 21 / AGP 8.7 错误、iOS 部署目标 13 错误，或已移除的废弃插件类型导致的 TypeScript 错误。
  • 用户要求确切的 6 -> 7 检查清单。

不适用场景

  • 应用在 5.x：先使用 capacitor-app-upgrade-v5-to-v6。
  • 应用在 7.x：使用 capacitor-app-upgrade-v7-to-v8。
  • 多跳升级规划：使用 capacitor-app-upgrades。
  • 插件库升级：使用 capacitor-plugin-upgrade-v6-to-v7。
  • 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'))"

参考资料

仅在相关主题出现时加载对应参考文件：

  • references/android.md：手动编辑 variables.gradle、build.gradle、wrapper、manifest 或 Kotlin 时加载。
  • references/plugins.md：应用使用官方 @capacitor/* 插件（App、Device、Haptics、Splash Screen、Status Bar 等）时加载。

预检要求

Capacitor 7 的最低工具要求：

  • Node.js：20+（建议最新 LTS）
  • Xcode：16.0+
  • iOS 部署目标：14.0
  • Android Studio：Ladybug 2024.2.1+（自带 JDK 21）
  • Java（Gradle JDK）：21
  • AGP / Gradle：8.7.2 / 8.11.1
  • Android SDK：minSdk 23、compileSdk 35、targetSdk 35

预检命令：

node -v && xcodebuild -version && java -version
git status --short
grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.*

操作步骤

  1. 从快照确认当前为 6.x。注意：将 minSdk 降至 23、iOS 降至 14 会移除对旧设备的支持，需告知用户。

  2. 运行自动迁移：

npm i -D @capacitor/cli@latest-7
npx cap migrate

该命令会升级包版本、将 iOS 部署目标和 Podfile 提升到 14.0、更新 Gradle 文件与 wrapper，并运行 cap sync。完成它报告为跳过或失败的每一步。

  1. 配置（capacitor.config.*）：
  • bundledWebRuntime 已移除。若为 false，直接删除；若为 true，应用必须使用打包器（Vite、webpack 等）打包 @capacitor/core，而不是加载 capacitor.js。
  • cordova.staticPlugins 已移除。需要静态链接的 Cordova 插件必须使用带 use-framework 的 podspec 标签（cordova-ios 7+ 不支持 framework 标签）。

  1. iOS：在 Build Settings 中将 Project 及每个 Target 的 iOS Deployment Target 设为 14.0，并在 ios/App/Podfile 中设置 platform :ios, '14.0'。对于 SPM 应用，检查 CapApp-SPM/Package.swift 的 platforms。

  2. Android：应用 references/android.md（AGP 8.7.2、Gradle 8.11.1、google-services 4.4.2、Kotlin 1.9.25，configChanges 中可选的 navigation）。

  3. 将 @capacitor/* 插件更新到 ^7.0.0，社区插件更新到其 Capacitor 7 版本。按 references/plugins.md 修复已移除的类型。

  4. 遥测对新 CLI 用户为选择退出，且从不在 CI 中运行。如需禁用，运行 npx cap telemetry off。

  5. 运行验证。

常见陷阱

  • 必须使用 JDK 21：Capacitor 7 的 Android 模块以 Java 21 源/目标编译，JDK 17 的 Gradle 运行时会报 invalid source release: 21。应修复 Gradle JDK（IDE 和 CI），而非代码。
  • 仍声明 minSdkVersion 22 或 iOS 13 的社区插件可以编译，但声明 @capacitor/core peer ^6 的插件会导致 npm ERESOLVE。应升级或替换它们；除非用户接受风险，否则避免 --legacy-peer-deps。
  • Device getInfo() 不再返回 diskFree、diskTotal、realDiskFree、realDiskTotal。仅在没有其他代码读取磁盘空间时，才移除对应的 PrivacyInfo.xcprivacy 磁盘空间条目。

验证

grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.*         # expect none
grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u   # 14.0
grep -n "platform :ios" ios/App/Podfile 2>/dev/null                     # '14.0'
grep -n "gradle:8.7.2\|google-services:4.4.2" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.11.1
grep -n "SdkVersion" android/variables.gradle                           # 23 / 35 / 35
grep -rnE "AppUrlOpen|AppRestoredResult|DeviceBatteryInfo|DeviceLanguageCodeResult|Haptics(Impact|Notification)(Options|Type|Style)|SplashScreen(Show|Hide)Options|diskFree|diskTotal" src/
npx cap sync
cd android && ./gradlew assembleDebug

然后在 Xcode 16+ 中构建 iOS 并启动两个平台。

错误处理

  • 报错 "Migrate can only be used on Capacitor 6, please use the CLI in Capacitor 6 to upgrade to 6 first"：先运行 capacitor-app-upgrade-v5-to-v6。
  • 报错 "Capacitor 7 requires JDK 21 or higher. Some steps may fail." 或 "invalid source release: 21"：将 Gradle JDK 设为 21（Android Studio Ladybug 自带），并在 CI 中同样设置。
  • 报错 "Skipped updating deployment target"：在 Xcode 和 Podfile 中手动设置 iOS 14.0（步骤 4）。
  • 报错 "Unable to find "<text>" in <file>. Try updating it manually"：应用 references/android.md 中的 diff。
  • 报错 "Module '"@capacitor/app"' has no exported member 'AppUrlOpen'"（或类似）：按 references/plugins.md 重命名为替代类型。
  • 报错 "ERESOLVE unable to resolve dependency tree on @capacitor/core"：某插件仍 peer 在 v6；将其升级到 v7 版本。