capacitor-plugin-upgrade-v6-to-v7

Capacitor 插件从 v6 升级到 v7

将插件库迁移到 Capacitor 7。权威信息来源：https://capacitorjs.com/docs/updating/plugins/7-0

适用情况

• 快照显示 @capacitor/core 为 6.x，且插件必须能在 Capacitor 7 应用中运行。
• 插件代码仍调用 call.success()、call.error()、registerWebPlugin、Capacitor.platform、Capacitor.isNative，或使用 BridgeFragment。
• Package.swift 将 capacitor-swift-pm 指向 branch: "main"。

请勿用于：

• 升级应用 → capacitor-app-upgrade-v6-to-v7。
• 插件为 5.x → 先使用 capacitor-plugin-upgrade-v5-to-v6；为 7.x → 使用 capacitor-plugin-upgrade-v7-to-v8。跨多个版本升级 → capacitor-plugin-upgrades。
• 从头添加 SPM → capacitor-plugin-spm-support。

实时项目快照

插件和 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=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

示例和原生项目路径： !find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' \)

参考资料

文件	查看时机
references/android.md	手动应用 Gradle、Java 或 Kotlin 更改时
references/ios.md	提高 podspec / Package.swift / 旧结构 Xcode 项目中的 iOS 目标版本，固定 capacitor-swift-pm 版本时
references/tooling.md	更新 eslint、swiftlint、prettier、rollup、rimraf、docgen 时

升级前检查

工具	最低要求
Node.js	20+
Xcode	16.0+
iOS 部署目标	14.0
Java	21
AGP / Gradle	8.7.2 / 8.11.1
Android SDK 默认值	minSdk 23，compileSdk 35，targetSdk 35

流程

1. 确认版本为 6.x，且工作区干净。

2. 在插件根目录运行：

   npx @capacitor/plugin-migration-v6-to-v7@latest
   

   检查 git diff。

3. package.json：将开发依赖 @capacitor/cli、core、android、ios 更新为 ^7.0.0；将对等依赖 @capacitor/core 更新为 >=7.0.0。工具链配置参见 references/tooling.md（注意将 rollup.config.js 重命名为 rollup.config.mjs，并在脚本标志中添加 --plugin=prettier-plugin-java）。

4. Android 参见 references/android.md：SDK 默认值设为 23/35/35，AGP 设为 8.7.2，Gradle 设为 8.11.1，Java 设为 21，Kotlin 设为 1.9.25。

5. iOS 参见 references/ios.md：podspec 设置 s.ios.deployment_target = '14.0'，Package.swift 设置 .iOS(.v14)，将 capacitor-swift-pm 设为 from: "7.0.0"，而不是 branch: "main"。

6. 已移除的 API——搜索并替换：

   • call.success(...) → call.resolve(...)；call.error(...) → call.reject(...)（Java/Kotlin 和 Swift）。
   • registerWebPlugin 和其他 v2 时代的定义已移除；请使用 registerPlugin（参见 Capacitor 3 插件升级指南）。
   • Capacitor.platform → Capacitor.getPlatform()；Capacitor.isNative → Capacitor.isNativePlatform()。
   • Android 的 BridgeFragment 已移除。如果插件通过它呈现 Fragment，请将所需逻辑复制到插件自有的 Fragment 类中。

7. 使用 capacitor-app-upgrade-v6-to-v7 升级示例应用，将插件主版本号递增，并注明“需要 Capacitor 7”。

验证

grep -n "\"@capacitor/\|rollup\|prettier\"" package.json
grep -rnE "\.success\(|\.error\(" android/src/main ios/ 2>/dev/null | grep -i call     # expect none
grep -rnE "registerWebPlugin|Capacitor\.platform\b|Capacitor\.isNative\b|BridgeFragment" src/ android/ ios/   # expect none
grep -n "deployment_target" *.podspec                       # '14.0'
grep -n "iOS(\|capacitor-swift-pm" Package.swift 2>/dev/null    # .v14, from: "7.0.0"
grep -n "VERSION_21\|gradle:8.7.2\|: 35\|: 23" android/build.gradle
npm run build
npm run verify        # if the repo has the template verify scripts

在两个平台上运行示例应用。

错误处理

错误	修复方法
cannot find symbol ... success( / error( on PluginCall	使用 resolve / reject。
invalid source release: 21	Gradle JDK 必须为 21。
SPM：目标平台要求的最低版本高于插件声明的版本	在 Package.swift 中设置 platforms: [.iOS(.v14)]，并将 capacitor-swift-pm 固定为 from: "7.0.0"。
Rollup 4 无法加载 rollup.config.js（ESM 配置）	重命名为 rollup.config.mjs 并更新 build 脚本。
Property 'platform' does not exist on type 'CapacitorGlobal'	使用 Capacitor.getPlatform()。