用途：把 Capacitor 插件库从 v8 升级到 v9。Capacitor 9 目前是预发布版本（next dist-tag，截至 2026 年 10 月为 9.0.0-alpha.x）；9.0.0 GA 后应改用 ^9.0.0 / from: "9.0.0"。发布仅支持预发布核心的稳定版插件前应先告知用户，常见做法是发布到 npm 的 next 标签下。规范来源见 Capacitor 官方插件升级文档。
适用时机：插件仓库 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、namespace 冲突）；无 Cordova 插件的消费应用因插件的 Cordova SPM 产物或 com.getcapacitor.cordova 导入而失败。
不适用：应用工程升级请用 capacitor-app-upgrade-v8-to-v9；仍停留在 7 或更早版本的插件请用 capacitor-plugin-upgrades 逐个大版本升级；为仅用 CocoaPods 的插件添加 SPM 请用 capacitor-plugin-spm-support；仅针对 8.5 UIScene 生命周期做检查请用 capacitor-uiscene-migration。
主要步骤：先读取项目快照、android/build.gradle、android/gradle.properties、.podspec、Package.swift 并列出原生源码，确认工作区干净；在插件根目录运行 npx @capacitor/plugin-migration-v8-to-v9@latest，再用 git diff 审查改动（该工具只覆盖大部分文件编辑，不处理代码中的 API 移除）；将 package.json 中 devDependencies 的 @capacitor/cli、core、android、ios 指向 next，peerDependencies["@capacitor/core"] 设为 >=9.0.0-alpha.6（以 npm view @capacitor/core dist-tags 为准），并询问是否仍需支持 8；按参考文档更新构建文件，同时保留 podspec 与 Package.swift；grep 并修复被移除的 API；移除 Package.swift 中无条件的 Cordova 产物依赖；按 UIScene 生命周期审查 iOS 代码；升级示例应用并更新 README 的安装与兼容表；按验证文档核对后升插件主版本号。
常见陷阱：AGP 9 默认 android.uniquePackageNames=true，脚手架默认 namespace 会导致消费应用构建失败；库模块的 targetSdkVersion 无运行时作用，应删除而非升级；CapacitorUrlRequest.setRequestHeaders 变覆盖而非追加；Package.swift 需指向 from: "9.0.0-alpha.6" 或更新的 capacitor-swift-pm；在插件根目录运行 npx cap sync 无意义，应在示例应用中运行。
限制：资料未提供具体价格、平台范围与效果数据。