Capacitor 9已在Capacitor上发布 next dist-tag 在逐步接近广泛可用状态的过程中。您不必在 alpha 版发布的那一天就升级您的应用，但 official Capacitor 9 update guide 并 Capacitor 9 插件更新指南 已经明确说明工具链的楼层和API的移除，值得早期解决。
本文是一篇关于Capacitor 9的准备指南。 准备 checklist: work you can do on Capacitor 8 (or on a branch) so the eventual bunx cap migrate 让过渡变得不那么枯燥，而不是痛苦。准备切换时，请逐步遵循上方的Ionic指南。
工具链和平台底座（应用）
规划CI、本地机器和存储管道，围绕这些最低要求:
| 区域 | Capacitor 9要求 |
|---|---|
| Node.js | 24+ （推荐使用最新的LTS版本；npm 11附带Node 24） |
| Xcode | 27+ |
| iOS目标 | 16.0+ |
| 安卓 studio | 2026.1.1+ |
| Android Gradle插件（AGP） | 9.2.1 |
| Gradle包装器 | 9.5.1 |
如果您仍在使用 Capacitor 8.4 或更早的 iOS 版本，您还需要 UIScene 生命周期 从 Capacitor 8.5 更新中获取 UIScene 生命周期工作 — Xcode 27 需要它。已经升级到 8.5 的应用程序可以跳过额外的步骤。
在 iOS 上，Swift 6 (与 Xcode 27) 拒绝 @UIApplicationMain; 当您升级时，请将其替换为 @main 在 AppDelegate.swift 如官方指南所述
在应用程序同步时间（不是插件预备步骤）
在 Capacitor 9 中，Cordova 兼容性层 仅在检测到安装的 Cordova 插件时 cap sync 为应用程序Android 在没有插件存在时会丢弃额外的 Gradle 模块；iOS 停止添加 CapacitorCordova 到 Podfile 或 Package.swift 当没有任何内容时。
这是一个 应用级别 行为改变，升级后。您仍在 Cap 8 上时，不需要提前从模板中移除 Cordova。请检查项目中是否有任何 自定义本机 code (您的或 forked 插件)导入 Cordova 符号，而没有实际的 Cordova 插件在项目中 — 这些引用将在 Cordova optional 绑定应用时失败。
Android： gradle.properties 和 AGP 9 默认值
AGP 升级助手经常写入明确的 gradle.properties 标志，以便构建保留 AGP 8 行为。Capacitor 9 应用应该 移除 那些条目而不是将它们带到前进：大多数在AGP 10之前就过时了，某些会破坏Cap 9构建（例如 android.builtInKotlin=false 禁用Kotlin支持，AGP 9捆绑的 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false 阻止AGP从 targetSdkVersion).
当您迁移时，还要预期：
- 升级
variables.gradle最小版本（编译/目标SDK 37，minSdkVersion26，更新的AndroidX版本 — 见官方文档）。 - 从应用中移除显式
targetSdkVersion以便AGP 9可以从build.gradle声明compileSdkVersion. - 符号在应用的顶部
variables.gradle符号在应用的顶部app/build.gradle(Gradle 9.6 已废弃隐式查找，从根项目中) - 当前上下一个安全一个为安全的网络。
core-ktxtoandroidx.core:core当前上下一个安全一个为安全的网络。jcenter().
提现不允许的安全为安全的网络。 当前上下一个安全一个为安全的网络。 在 Android 部分并应用同样的清理工作在一个分支上，然后在推送 Capacitor 版本之前。
CLI: cap run --url
Capacitor 9 将 live-reload 主机/端口/HTTPS 标志合并为一个 --url 当前上下一个安全一个为安全的网络。
bunx cap run android -l --host 192.168.1.181 --port 5173提现不允许的安全为安全的网络。
bunx cap run android --url http://192.168.1.181:5173/更新脚本和README片段，现在让肌肉记忆不会与升级后的CLI产生冲突。
官方插件：推送和启动屏幕注意事项
在生产应用中经常出现的两个用户界面变化是：
推送通知（iOS）： 已弃用的 alert presentation选项已删除。请使用 banner 和/或 list 在您的
启动屏幕（Android）： 默认 launchFadeOutDuration 从 200 ms 到 0. If you relied on the fade hiding first paint glitches, set launchFadeOutDuration: 200 明确地在 capacitor.config 直到您调整启动 UI
扫描插件部分在 9.0更新指南 为 AndroidX 和 Google Play 服务版本升级
与您使用的官方插件相关联
如果您发布 Capacitor 插件，它们将在 Capacitor 8 中被消费。 而不破坏 Cap 8 如果您发布 code 插件 已废弃的API移除并
想要 Cap 9-ready __CAPGO_KEEP_0__，专注于
- 替换
@NativePlugin为@CapacitorPlugin并将遗留的权限/活动结果API迁移到@PermissionCallback/@ActivityCallback模式（参见 插件9.0指南 表格）。 - 移除
PluginCall.hasOption,Plugin.getConfigValue,旧CapConfig构造函数和获取器,PluginCall.save()/isSaved(),以及其他Java移除的列表在“code”中的“Breaking changes”。 - 在iOS上，停止使用
CAPBridge兼容性类和已弃用的CAPBridgeProtocolhelpers; 使用ApplicationDelegateProxy, typedPluginCall从迁移表中获取访问器和桥接属性。 - Run
bunx @capacitor/plugin-migration-v8-to-v9@latest在Capacitor 9发布之前，保持Cap 8的依赖项，仅保留API的编辑项，直到您发布Cap 9的主要版本。
不要从您的插件中移除 Cordova SPM产品 Package.swift 在您仍然支持Cap 8时不要移除Capacitor。 Cap 8项目期望在您的插件是SPM-基于时使用该依赖项；提前移除它会破坏仍然在8上运行的消费者。将 可选的Cordova / 移除条件的 Cordova 产品 作为 Capacitor 9-only 发布 Cap 9 的线路（或明确文档为 Cap 9+ 的 semver 主版本），在您停止支持 Cap 8 时 — 如 plugin 指南所述，而不是 Cap 8 线路的预备工作。
同样的经验法则适用于升级 capacitor-swift-pm 到 9.0.0-alpha.x 在 Package.swift: 属于您的 Cap 9 主版本，而不是 Cap-8 兼容的发布。
Capgo 实时更新和原生 Cap 9 商店构建
Capgo 提供 web 包 实时更新；原生 shell 仍然来自 App Store 和 Google Play。 当您将应用程序迁移到 Capacitor 9 时：
- 发布 至少有一份商店构建 基于 Capacitor 9 编译了 140 个原生项目（iOS 和 Android）。该二进制文件确定了原生基线 Capgo 通道的目标。
- 只有当用户手中有该构建后，您才能依赖测试过 Cap 9 WebView 和插件行为的 OTA 包。
- 将生产通道置于策略中，并将匹配的 Cap 9 包上传到每个通道中。
metadata为此有意的原生基线上传，--auto-min-update-version忽略 (原生包应该改变)。保持--fail-on-incompatible并--fail-on-incompatibleand--auto-min-update-version原生 + OTA 通道工作流 保持通道和 SemVer 规则一致，以便您永远不会推送一个假设 Cap 9 API 的包到仍在运行旧式原生 shell 的设备上。. - 如果您使用
策略 Capgo 构建 或您的CI，刷新代理 之前 Cap 9 商店发布之前，管道应与用户安装的匹配： macOS 运行器需要 Node 24+ 和 Xcode 27+; Linux 运行器需要 Node 24+ 和与 AGP 9.2.1 / Gradle 9.5.1 (Xcode仅限macOS).
建议的操作顺序
- 升级安装的工具 在CI主机和开发机器上升级到 (Node, Xcode, Android Studio, JDK) 的更高版本。 不要 在Cap 8应用的AGP依赖项、Gradle包装器或其他Android项目文件中
bunx cap migrate升级到Cap 9值， - 直到 在应用程序code和插件（尤其是自定义）
AppDelegate那些项目更改属于迁移步骤。 - 修复应用 __CAPGO_KEEP_0__ 和插件中的过时原生API（特别是自定义 URL处理和Android桥接使用）。
gradle.properties清理Android Gradle--url文件和脚本（包括 ProGuard 默认值， - 审计 Cordova 在应用级别使用 Cordova，直到 Cap 9-only 发布版本发布之前，不要更改插件 SPM Cordova 产品。
- 当 Cap 9 GA (或您接受
next) 时，运行bun add -d @capacitor/cli@next(或@latest)，然后bunx cap migrate在发布之后， ，并遵循. - 升级到 9.0 到商店，接着恢复或扩展匹配频道的Capgo OTA升级。
到商店，然后恢复或扩展 Capacitor OTA 滚动更新到匹配的频道。
