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

capacitor-plugin-upgrade-v4-to-v5

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

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

用于将 Capacitor 插件库从 v4 迁移到 v5 的技能，涵盖依赖、Android 和 iOS 修改，并提供原生构建与空值检查步骤。

主要功能

  1. 01项目快照与版本检查
  2. 02自动迁移命令
  3. 03Android 与 iOS 手动更新指南
  4. 04构建和迁移验证

适用场景

  1. 01让 v4 插件适配 Capacitor 5 应用
  2. 02修复 Android 命名空间或 Java 17 构建错误
  3. 03更新插件桥接代码以适配 Capacitor 5

安装

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

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

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

附带文件metadata.jsonreferences/android.md

详细介绍

Capacitor 插件从 v4 升级到 v5

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

适用场景

  • 快照显示 @capacitor/core 在 peer/dev 依赖中为 4.x，且插件必须能在 Capacitor 5 应用中运行。
  • Capacitor 5 应用构建此插件时失败，并提示 Namespace not specified 或 Java 17 错误。
  • 插件手动实现 CAPBridgedPlugin，或调用 getObject() / getArray()。

请勿用于：

  • 升级应用 → capacitor-app-upgrade-v4-to-v5。
  • 插件已使用 5 → capacitor-plugin-upgrade-v5-to-v6。跨多个版本升级 → capacitor-plugin-upgrades。

当前项目快照

插件和 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 更改时

预检

工具最低版本
Node.js16+
Xcode14.1+
Java17（AGP 8）
AGP / Gradle8.0.0 / 8.0.2
Android SDK 默认值compileSdk 33，targetSdk 33，minSdk 22
iOS 部署目标13.0（不变）

操作步骤

  1. 确认快照显示插件使用 4.x，且工作区干净（git status）。

  2. 在插件根目录运行：

    npx @capacitor/plugin-migration-v4-to-v5@latest

    此操作会修改 package.json、android/build.gradle、包装器、gradle.properties 和清单。请检查 git diff。

  3. 手动完成未应用的更改（references/android.md）：

    • 将 @capacitor/cli、core、android、ios 的开发依赖更新到 latest-5；将 peer 依赖 @capacitor/core 更新到 ^5.0.0。
    • SDK 默认值设为 33，AGP 设为 8.0.0，Gradle 设为 8.0.2；在 android {} 中添加 namespace，并从清单中移除 package=；使用 Java 17，移除 Jetifier，将 Kotlin 更新到 1.8.20 并使用 kotlin-stdlib。

  4. iOS 代码：如果插件手动实现 CAPBridgedPlugin（不使用 CAP_PLUGIN 宏），将要求移至实例级别，将 pluginId 重命名为 identifier，将 pluginMethods 声明为 [CAPPluginMethod]，并移除 getMethod(_:)。基于宏的插件无需更改。

  5. Android 代码：call.getObject(key) 和 call.getArray(key) 现在可能返回 null。请添加空值检查；如果值必需，则调用 call.reject(...) 并提供清晰的消息。

  6. 如果存在示例应用，请通过 capacitor-app-upgrade-v4-to-v5 将其更新到 Capacitor 5。

  7. 将插件主版本号递增，并在变更日志或 README 中注明“需要 Capacitor 5”。

验证

grep -n "\"@capacitor/" package.json                         # 5.x everywhere
grep -n "package=" android/src/main/AndroidManifest.xml      # expect none
grep -n "namespace\|VERSION_17\|gradle:8.0.0" android/build.gradle
grep -rn "kotlin-stdlib-jdk" android/build.gradle            # expect none
grep -rn "getObject(\|getArray(" android/src/main/           # each result null-checked
grep -rn "pluginId\b" ios/                                   # only CAPPlugin usages remain
npm run build
npm run verify        # plugin template script: verify:ios + verify:android + verify:web, if present
cd android && ./gradlew clean build test

在两个平台上运行示例应用，并测试每个方法。

错误处理

错误修复方法
Namespace not specified在插件的 build.gradle 中的 android {} 添加 namespace "<package>"。
Android Gradle plugin requires Java 17 to run将 Gradle JDK 切换到 17。
getObject/getArray 引发 NullPointerException添加空值检查（步骤 5）。
Swift：类型不符合协议 CAPBridgedPlugin使用实例级别的 identifier、jsName、pluginMethods，或改用宏。
Duplicate class ... kotlin-stdlib-jdk8将 kotlin-stdlib-jdk7/jdk8 替换为 kotlin-stdlib。

评论

支持 Markdown