用途：把基于 @capacitor/core 8.x 的应用升级到 Capacitor 9，覆盖预检、依赖与原生文件迁移、逐项人工核对、同步构建与验证。官方文档见 https://capacitorjs.com/docs/updating/9-0。
何时使用：应用在 8.x 且需升级到 9；迁移到 Xcode 27 / Swift 6、AGP 9 或 Gradle 9 后出现构建错误；npx cap run -l 失效（改用 --url）；iOS 推送 presentationOptions 不再显示横幅；无 Cordova 插件的应用在升级后因 CapacitorCordova / com.getcapacitor.cordova 引用报错。
不适用：应用仍在 7 或更早（先用 capacitor-app-upgrades 逐版本升级）；仅做 8.4→8.5 的 UIScene 步骤（用 capacitor-uiscene-migration）；插件库仓库（用 capacitor-plugin-upgrade-v8-to-v9）；CocoaPods 转 SPM（用 cocoapods-to-spm）。
使用方式：
- 预检（失败则停止并报告）：node --version 需 ≥24；xcodebuild -version 需 Xcode 27+；java 使用 Android Studio 2026.1.1+ 自带 JDK；确认 ios/App/App/Info.plist 含 UIApplicationSceneManifest；git 工作区干净。未采用 UIScene 的应用需先在 8.5 上运行 capacitor-uiscene-migration 并验证。迁移前清点原生定制，如 AppDelegate/SceneDelegate 代码、CAPBridgeViewController 子类、本地插件、variables.gradle 变量与 Cordova 插件。
- 安装与自动迁移：npm i -D @capacitor/cli@next，然后 npx cap migrate；后者不适合 monorepo，需手工迁移。随后把所有 @capacitor/* 包升到 @next，并检查第三方插件是否有兼容 Capacitor 9 的版本。
- 人工核对清单：iOS（Xcode 27、iOS 16.0、@main、移除 CAPBridge/bridge API、建议 SPM）；Android（gradle.properties 清理、variables.gradle、移除 targetSdkVersion、使用 proguard-android-optimize.txt、AGP 9.2.1、Gradle 9.5.1、google-services 4.5.0 等）；插件、CLI 与配置（推送、启动屏、cap run --url、Cordova 运行时可选）。
- 执行 npx cap sync，再按验证清单做残留符号检查、两端原生构建与真机检查，分平台报告结果。
限制与注意：Capacitor 9 为预发布，生产应用升级前需告知用户并新建分支。gradle.properties 中残留 AGP 8 兼容项、proguard-android.txt、重复 Kotlin 插件、core-ktx 重复类、未声明的 rootProject.ext 属性、命名空间冲突等均会导致失败。无 Cordova 插件的应用不再包含 CapacitorCordova，相关原生代码将无法编译，且无强制包含开关。旧版 AppDelegate 的 URL 处理逻辑需移到 SceneDelegate。CocoaPods Trunk 预计 2026 年 12 月 2 日转只读，升级通过后可选做 cocoapods-to-spm。其余未提供细节暂未说明。