capacitor-plugin-upgrade-v8-to-v9

Capacitor 插件从 v8 升级到 v9

Capacitor 9 目前为预发布版本（截至 2026 年 10 月，next dist-tag，版本为 9.0.0-alpha.x）。下方的依赖范围面向预发布版本；9.0.0 GA 发布后，请使用 ^9.0.0 / from: "9.0.0"。如果稳定版插件仅支持预发布版核心，请在发布前告知用户；一种常见做法是使用 npm next 标签发布。

规范来源：https://capacitorjs.com/docs/updating/plugins/9-0

适用场景

在以下情况触发：

• 插件仓库中的 peerDependencies["@capacitor/core"] 为 ^8 或 >=8，且用户希望支持 Capacitor 9
• 插件因使用已移除的 API（CAPBridge、@NativePlugin、saveCall、getWebView()、isSimulator()）而无法针对 Capacitor 9 编译
• 插件的 android/build.gradle 在 AGP 9 / Gradle 9 下构建失败（jcenter()、kotlin-android、proguard-android.txt、命名空间冲突）
• 未使用 Cordova 插件的使用方应用在插件的 Cordova SPM 产品或 com.getcapacitor.cordova 导入处失败

请勿用于：

• 应用项目 -> capacitor-app-upgrade-v8-to-v9
• 插件仍处于 v7 或更早版本 -> capacitor-plugin-upgrades（按主版本逐级升级）
• 为仅支持 CocoaPods 的插件添加 SPM -> capacitor-plugin-spm-support
• 仅针对 8.5 UIScene 生命周期检查插件 -> capacitor-uiscene-migration（references/plugin-audit.md）

当前项目快照

!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)}}out.push('Package.swift='+fs.existsSync('Package.swift'));out.push('podspec='+fs.readdirSync('.').filter(f=>f.endsWith('.podspec')).join(','));console.log(out.join('\n'))"

!find . -maxdepth 3 \( -path './example-app' -o -path './example' -o -path './ios' -o -path './android' \) -not -path './node_modules/*'

流程

1. 检查。 阅读快照、android/build.gradle、android/gradle.properties、.podspec、Package.swift，并列出原生源码（android/src/main、ios/Sources 或 ios/Plugin）。记下示例应用的路径。确认工作树干净（git status）。
2. 运行迁移工具，位置为插件根目录：

   npx @capacitor/plugin-migration-v8-to-v9@latest
   

   检查差异（git diff）。它涵盖了大部分文件修改，但不包括代码中的 API 移除。
3. 依赖项（位于 package.json）：
   • devDependencies：将 @capacitor/cli、@capacitor/core、@capacitor/android、@capacitor/ios 升级到 next。
   • peerDependencies["@capacitor/core"]：设为 >=9.0.0-alpha.6（运行 npm view @capacitor/core dist-tags 查看当前预发布版本）。询问此版本是否仍应支持 8；大多数插件会移除对它的支持，因为 iOS 16 / AGP 9 的构建变更不向后兼容。
4. 构建文件：参照 references/build-files.md（gradle.properties、build.gradle、podspec、Package.swift）。保留 podspec 和 Package.swift：使用 CocoaPods 和 SPM 的应用都会使用该插件。
5. 代码 API 移除。 搜索后，参照 references/android-api-removals.md 和 references/ios-api-removals.md 修复每一处命中。不要将已弃用的调用路径留在 #if 或反射代码后面。
6. Cordova 可选性。 从 Package.swift 中移除无条件的 .product(name: "Cordova", ...)。如果插件的原生代码导入了 Cordova 兼容类（com.getcapacitor.cordova.*、CDV*），在没有 Cordova 插件的应用中就会出错；请询问用户应如何替换它。
7. UIScene 生命周期。 每个 Capacitor 9 应用都基于场景。检查 iOS 代码是否依赖 AppDelegate 方法、tmpWindow、通过 keyWindow 展示内容、applicationState（参见 capacitor-uiscene-migration -> references/plugin-audit.md）。现在最低版本为 9，可以安全使用 .capacitorScene* 通知和 SceneDelegateProxy。
8. 示例应用和文档。 使用 capacitor-app-upgrade-v8-to-v9 升级示例应用。更新 README 安装说明和兼容性表（Capacitor 9、iOS 16、minSdk 26）。
9. 验证：参照 references/verification.md。将插件主版本号加 1。

陷阱

• AGP 9 默认启用 android.uniquePackageNames=true：脚手架默认命名空间（com.mycompany.plugins.example）或沿用上游命名空间的分支会导致使用该插件的应用构建失败。请设置唯一的命名空间。
• 库模块中的 targetSdkVersion 不会影响运行时；应将其删除，而不是升级。
• CapacitorUrlRequest.setRequestHeaders([String: Any]) 会设置值，而不是追加；现在重复的标头键会相互覆盖。
• Package.swift 中必须将 capacitor-swift-pm 指向 from: "9.0.0-alpha.6" 或更高版本（更早的 alpha 版本在 Cordova 可选性方面会导致崩溃）。使用最新的 alpha 版本。
• googleMapsUtilsVersion 5.0.0 包含上游破坏性 API 变更。
• 在插件根目录运行 npx cap sync 没有用；应在示例应用中运行 sync。

错误处理

错误	修复方法
cannot find symbol ... class NativePlugin	@CapacitorPlugin(name = ..., permissions = ...)
cannot find symbol ... method saveCall(PluginCall)	call.setKeepAlive(true) 或 bridge.saveCall(call)
cannot find symbol ... method pluginRequestPermission(...)	requestPermissionForAlias(alias, call, "callbackName") + @PermissionCallback
Cannot find 'CAPBridge' in scope	ApplicationDelegateProxy.shared / Notification.Name.capacitorStatusBarTapped
Value of type 'CAPBridgeProtocol' has no member 'getWebView'	bridge?.webView（其他 getter 也采用相同模式 -> 属性）
AGP 9 下出现 Kotlin 插件重复或冲突错误	移除独立的 Kotlin 插件和 stdlib
使用该插件的应用中出现命名空间冲突 / 包重复	在 android/build.gradle 中设置唯一的 namespace
使用该插件的应用中出现提及 Cordova 的 SPM 解析或链接错误	移除 Cordova 产品依赖

参考资料

仅在涉及相应主题时加载参考资料。

文件	加载时机
references/build-files.md	编辑 gradle.properties、build.gradle、podspec、Package.swift 或 wrapper 时
references/android-api-removals.md	出现任何 Java/Kotlin 编译错误或 grep 命中时
references/ios-api-removals.md	出现任何 Swift/ObjC 编译错误或 grep 命中时
references/verification.md	编辑后：执行 grep、构建、示例应用检查和发布时

相关技能：capacitor-plugin-upgrades、capacitor-app-upgrade-v8-to-v9、capacitor-uiscene-migration、capacitor-plugin-spm-support。