mcpField
C
capacitor-app-upgrade-v6-to-v7

capacitor-app-upgrade-v6-to-v7

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

关于 capacitor-app-upgrade-v6-to-v7

面向 Capacitor 6 应用的迁移技能，指导项目升级到 Capacitor 7。涵盖自动迁移、iOS 与 Android 配置、插件更新和验证，并列出常见错误处理方法。

主要功能

  1. 01检查项目版本与构建环境
  2. 02运行 CLI 自动迁移
  3. 03更新 iOS 与 Android 配置
  4. 04升级插件并修复类型变更
  5. 05执行构建与迁移验证

适用场景

  1. 01将 Capacitor 6 应用升级到 7
  2. 02排查升级后的 JDK 或 AGP 构建错误
  3. 03处理 iOS 部署目标与插件类型变更

安装

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

$npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-app-upgrade-v6-to-v7

安装后在 Claude Code 中输入/capacitor-app-upgrade-v6-to-v7确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
references/
android.md
plugins.md

详细介绍

Capacitor 应用从 v6 升级到 v7

将 Capacitor 6 应用升级到 Capacitor 7。权威来源：https://capacitorjs.com/docs/updating/7-0

适用场景

  • 以下快照中的 @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.js20+（建议使用最新的 LTS 版本）
Xcode16.0+
iOS 部署目标14.0
Android StudioLadybug 2024.2.1+（附带 JDK 21）
Java（Gradle JDK）21
AGP / Gradle8.7.2 / 8.11.1
Android SDKminSdk 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。完成所有报告为跳过或失败的步骤。

  3. 配置（capacitor.config.*）：

    • bundledWebRuntime 已移除。值为 false -> 删除该项。值为 true -> 应用必须使用打包工具（Vite、webpack 等）打包 @capacitor/core，而不是加载 capacitor.js。
    • cordova.staticPlugins 已移除。需要静态链接的 Cordova 插件必须使用带有 use-framework 的 podspec 标签（cordova-ios 7+ 不支持 framework 标签）。

  4. iOS：在 Build Settings 中为项目和每个 Target 设置 iOS Deployment Target = 14.0，并在 ios/App/Podfile 中设置 platform :ios, '14.0'。对于 SPM 应用，检查 CapApp-SPM/Package.swift 中的平台设置。

  5. Android：按照 references/android.md 中的说明进行设置（AGP 8.7.2、Gradle 8.11.1、google-services 4.4.2、Kotlin 1.9.25，以及 configChanges 中可选的 navigation）。

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

  7. 新 CLI 用户默认启用遥测，但遥测不会在 CI 中运行。如果用户希望关闭遥测，请运行 npx cap telemetry off。

  8. 运行验证。

注意事项

  • 必须使用 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 中的差异。
Module '"@capacitor/app"' has no exported member 'AppUrlOpen'（或类似错误）在 references/plugins.md 中将其重命名为替代类型。
ERESOLVE unable to resolve dependency tree，涉及 @capacitor/core某个插件仍依赖 v6；将其升级到 v7 版本。

评论

支持 Markdown