mcpField
C
capacitor-app-upgrade-v4-to-v5

capacitor-app-upgrade-v4-to-v5

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

关于 capacitor-app-upgrade-v4-to-v5

面向 Capacitor 4 应用的迁移技能，指导项目升级到 Capacitor 5。提供工具链检查、CLI 迁移步骤、iOS 与 Android 调整及验证清单。

主要功能

  1. 01检查项目版本与工具链要求
  2. 02运行 CLI 自动迁移
  3. 03调整 iOS 与 Android 配置
  4. 04更新官方及社区插件
  5. 05验证构建并处理常见错误

适用场景

  1. 01将 Capacitor 4 应用升级到 5
  2. 02处理 Android namespace 或 Java 版本错误
  3. 03检查插件变更和升级后的数据保留

安装

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

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

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

包含的文件

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

metadata.json
references/
android.md
plugins.md

详细介绍

Capacitor 应用从 v4 升级到 v5

将 Capacitor 4 应用迁移到 Capacitor 5。权威来源：https://capacitorjs.com/docs/updating/5-0

适用场景

  • 下方快照中的 @capacitor/core 为 4.x，且用户希望升级到 5.x。
  • 升级到 Capacitor 5 后 Android 构建失败，并出现 Namespace not specified、Java 11 与 17 不匹配或 AGP 8 错误。
  • 用户需要 iOS、Android 或官方插件从 4 升级到 5 的具体检查清单。

请勿用于：

  • 应用已使用 5.x 或更高版本 → 使用 capacitor-app-upgrade-v5-to-v6（然后依次升级 v6 到 v7、v7 到 v8）。多阶段升级规划 → capacitor-app-upgrades。
  • 升级插件库 → 使用 capacitor-plugin-upgrade-v4-to-v5。
  • 应用使用 3.x → 先升级到 4（在 5.x 中，npx cap migrate 不接受低于 4 的项目）。

实时项目快照

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/* 插件（Camera、Device、Push、Local Notifications、Google Maps 等）时

升级前检查

修改文件前先检查并报告。如果缺少任何最低要求，请要求用户先升级工具链。

工具Capacitor 5 的最低要求
Node.js16+（建议使用最新 LTS 版本）
Xcode14.1+
Android StudioFlamingo 2022.2.1+（附带 JDK 17）
Java（Gradle JDK）17
AGP / Gradle8.0.0 / 8.0.2
Android SDKminSdk 22，compileSdk 33，targetSdk 33
iOS 部署目标13.0（与 v4 相同）
node -v
xcodebuild -version
java -version
git status --short   # start from a clean tree so the migration diff is reviewable

流程

  1. 根据快照确认 @capacitor/core 为 4.x。如果低于 4，请停止并先转到 3 → 4 升级流程。

  2. 运行自动迁移：

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

    该命令会升级 @capacitor/* 包、更新 variables.gradle、AGP 和 Gradle wrapper，将 package 移至 namespace，精简 iOS 应用图标集，并运行 cap sync。阅读输出：所有未能自动完成的步骤都会列出，必须手动完成。

  3. 检查 git diff。然后完成 CLI 跳过的所有事项：

    • iOS：在 ios/.gitignore 中将 App/Podfile.lock 替换为 App/output（从现在起提交 Podfile.lock）。也可以将 AppIcon.appiconset 精简为单个 1024x1024 图标。
    • Android：应用 references/android.md 中的变量表和差异（AGP 8.0.0、Gradle 8.0.2、google-services 4.3.15、namespace、Jetifier、Kotlin 1.8.20）。
    • 配置：如果未设置 server.androidScheme，请在 capacitor.config.* 中添加 androidScheme: "http"。Capacitor 6 会将默认值改为 https，这会改变 WebView 来源，并清除 localStorage、IndexedDB 和 cookies。现在固定该值可避免日后数据丢失。若要改用 https，请先征求用户同意。

  4. 将所有官方插件更新到 ^5.0.0，并将社区插件更新到其 Capacitor 5 版本。应用 references/plugins.md 中的代码更改。

  5. 在 Android Studio 中，如果 Gradle 文件仍显示 AGP 7 的残留配置，请运行 Tools -> AGP Upgrade Assistant。

  6. 运行下方的验证步骤。

常见陷阱

  • 移除 android.enableJetifier=true 会导致构建失败，前提是仍有依赖使用旧版 android.support.* 库。请先搜索 node_modules 和原生依赖；如果不确定，请保留 Jetifier。
  • namespace 必须与旧清单中的 package 值一致；如果两者不同，则不能使用 applicationId。
  • 设备插件：getId() 现在返回 { identifier }；uuid 已移除。在 iOS 16+ 上，如果没有用户指定设备名称的 entitlement，DeviceInfo.name 会返回通用名称。
  • Android 13（targetSdk 33）：Push 和 Local Notifications 需要在运行时调用 checkPermissions() / requestPermissions()，否则不会显示任何内容。

验证

grep -rn "package=" android/app/src/main/AndroidManifest.xml          # expect no package attribute
grep -n "namespace" android/app/build.gradle                          # expect namespace "<id>"
grep -n "gradle:8.0.0\|google-services" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties  # gradle-8.0.2
grep -n "SdkVersion" android/variables.gradle                         # 22 / 33 / 33
grep -rn "androidScheme" capacitor.config.*                           # explicit value present
grep -rn "\.uuid\b" src/                                              # no Device uuid leftovers
npx cap sync
cd android && ./gradlew assembleDebug

然后在 Xcode 14.1+ 中构建 iOS（或运行 npx cap run ios），并启动两个平台。确认存储的数据（登录信息、localStorage）在升级后仍然保留。

错误处理

错误解决方法
Migrate can only be used on capacitor 4 and above, please use the CLI in Capacitor 4 to upgrade to 4 first项目使用的是 3.x。请先升级到 4。
Capacitor 5 requires JDK 17 or higher. Some steps may fail.将 Gradle JDK 设置为 17（Android Studio Settings -> Build Tools -> Gradle），然后重新运行。
Unable to find <file>. Try updating it manually应用 references/android.md 中对应的 diff。
Found namespace in build.gradle already, skipping migration这是提示信息。只需确认清单中不再包含 package=。
Namespace not specified（Gradle）在出错模块的 android {} 块中添加 namespace "<package id>"。对于第三方插件，请将其更新到 Capacitor 5 版本。
Android Gradle plugin requires Java 17 to run. You are currently using Java 11.将 Gradle JDK 切换为 17。
升级后 Android 上数据丢失 / 已退出登录androidScheme 已更改。将其恢复为已安装应用使用的 scheme（v4 默认值为 http）。

评论

支持 Markdown