capacitor-app-upgrade-v5-to-v6

Capacitor App 从 v5 升级到 v6

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

适用场景

• 下方快照中的 @capacitor/core 为 5.x，且用户希望升级到 6.x。
• 升级后：Android 用户丢失 localStorage/ Cookie；本地（非 npm）iOS 插件报告 "<Name>" plugin is not implemented on ios；iOS 上捏合缩放停止工作；或出现与 addListener 相关的 TypeScript 错误。
• 用户要求提供准确的 5 -> 6 检查清单。

请勿用于：

• 应用为 4.x -> 先使用 capacitor-app-upgrade-v4-to-v5。应用为 6.x -> 使用 capacitor-app-upgrade-v6-to-v7。多版本跳跃规划 -> 使用 capacitor-app-upgrades。
• 插件库升级 -> 使用 capacitor-plugin-upgrade-v5-to-v6。
• 将 iOS 从 CocoaPods 迁移到 SPM（在 6 中为实验性功能）-> 使用 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 或 Kotlin 时
references/plugins.md	应用使用官方 @capacitor/* 插件，或保存 addListener 返回值时

升级前检查

工具	Capacitor 6 的最低要求
Node.js	18+（建议使用最新 LTS 版本）
Xcode	15.0+
Android Studio	Hedgehog 2023.1.1+
Java（Gradle JDK）	17
AGP / Gradle	8.2.1 / 8.2.1
Android SDK	minSdk 22、compileSdk 34、targetSdk 34
iOS 部署目标	13.0（不变）

node -v && xcodebuild -version && java -version
git status --short
grep -rn "androidScheme" capacitor.config.*   # decide the scheme BEFORE migrating

流程

1. 根据快照确认版本为 5.x。

2. 先确定 androidScheme（需要判断；不明确时询问用户）。Capacitor 6 会将现有应用的默认值设为 https。更改 scheme 会改变 WebView 来源，因此已安装应用中的 localStorage、IndexedDB、Cookie 和 service worker 将无法再读取。

   • 当前未设置 androidScheme -> 添加 server: { androidScheme: "http" } 以保留用户数据。
   • 已设置为 "https" -> 可以移除该项。

3. 运行自动迁移：

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

   阅读输出，并完成所有报告为失败的步骤。

4. iOS：

   • 插件类不再自动注册。npm 插件由 CLI 生成的列表处理。在应用目标中编写的本地插件（自定义代码指南）需要一个 CAPBridgeViewController 子类，该子类重写 capacitorDidLoad() 并调用 bridge?.registerPluginInstance(MyPlugin())；Main.storyboard 必须将该子类设为视图控制器的自定义类。
   • 默认禁用缩放。如果应用依赖捏合缩放，请在 Capacitor 配置中设置 zoomEnabled: true。

5. Android：应用 references/android.md 中的设置（AGP 8.2.1、Gradle 8.2.1、google-services 4.4.0、compileSdk、Kotlin 1.9.10）。

6. 将所有 @capacitor/* 插件更新到 ^6.0.0，并将社区插件更新到其 Capacitor 6 版本。根据 references/plugins.md 修复代码。

7. 运行验证。

注意事项

• addListener 现在只返回 Promise<PluginListenerHandle>。const h = Plugin.addListener(...); h.remove() 将无法编译；请使用 const h = await Plugin.addListener(...)。
• Camera 现在使用 Android Photo Picker。在 Android 上，取消图库选择会像其他平台一样以 "User cancelled photos app" 错误拒绝；请更新错误匹配逻辑。
• iOS 上的 Filesystem stat() 会将 ctime / mtime 作为数字而非字符串返回。
• 如果设置了 saveToGallery: true，或其他插件需要这些权限，请勿移除 READ_MEDIA_IMAGES / 存储权限。

验证

grep -rn "androidScheme" capacitor.config.*                 # explicit decision recorded
grep -n "compileSdkVersion rootProject" android/app/build.gradle   # expect none (now compileSdk)
grep -n "gradle:8.2.1\|google-services:4.4.0" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.2.1
grep -n "SdkVersion" android/variables.gradle                # 22 / 34 / 34
grep -rnE "= *[A-Za-z]+\.addListener\(" src/                 # each must be awaited
grep -rn "registerPluginInstance" ios/App/App/               # present if the app has local plugins
npx cap sync
cd android && ./gradlew assembleDebug

在 Xcode 15+ 中构建并启动 iOS。在安装了 v5 版本的设备上原位升级，并确认登录状态/localStorage 得以保留。

错误处理

错误	解决方法
Migrate can only be used on capacitor 5 and above, please use the CLI in Capacitor 5 to upgrade to 5 first	先运行 capacitor-app-upgrade-v4-to-v5。
Capacitor 6 requires JDK 17 or higher. Some steps may fail.	将 Gradle JDK 设置为 17 或更高版本。
Unable to find "<text>" in <file>. Try updating it manually	应用 references/android.md 中的差异。
"<Plugin>" plugin is not implemented on ios（本地插件）	在 CAPBridgeViewController 子类中注册它（步骤 4）。
Property 'remove' does not exist on type 'Promise<PluginListenerHandle>'	对 addListener 调用使用 await。
Android 上的用户已注销／数据丢失	Scheme 已更改。恢复之前的 androidScheme 值。