Capacitor 9: App 和插件团队现在可以做什么

Capacitor 9已在Capacitor上发布 next 您不必在 alpha 发布的第一天升级您的应用程序 official Capacitor 9 update guide 并插件更新指南已经说明工具链地板和API移除值得早期处理。

关于Capacitor 9的准备准备清单：您可以在Capacitor 8（或分支）上进行的工作，以便最终过渡变得乏味而不是痛苦。当您准备切换时，请逐行遵循上面链接的Ionic指南。 bunx cap migrate 工具链和平台地板（应用）

规划您的CI、本地机器和商店管道围绕这些最低要求:

区域

context	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 更新中获取工作 — Xcode 27 需要它。已经升级到 8.5 的应用程序可以跳过额外的步骤。

在 iOS 上，Swift 6 (与 Xcode 27) 拒绝 @UIApplicationMain; @main 当您升级时，替换为 AppDelegate.swift ，

如官方指南所述，在应用程序同步时间 (不是插件预备步骤) 中使用 Cordova

In Capacitor 9，Cordova兼容层将只在检测到安装的Cordova插件时与您的应用程序进行连接。 仅在检测到安装的Cordova插件时 cap sync 检测到安装的Cordova插件.安卓将在没有额外Gradle模块的情况下丢弃额外的Gradle模块；iOS将停止在没有额外模块的情况下添加 CapacitorCordova 到Podfile或 Package.swift 当没有额外模块时

这是一个 应用级别 行为变化，升级后您仍然在Cap 8上，您不需要提前从模板中移除Cordova。您需要审计一下是否有任何 自定义本机code (您自己的或forked插件)导入Cordova符号，而没有实际的Cordova插件在项目中——这些引用将在可选的Cordova连接应用时失败。

安卓： `gradle.properties` 和 AGP 9 默认值

升级助手通常会明确写入 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, minSdkVersion 26，更新的 AndroidX 版本 —— 参见官方文档）。
移除明确 targetSdkVersion 从应用程序 build.gradle 所以 AGP 9 可以从 compileSdkVersion.
声明 variables.gradle 符号在顶部 app/build.gradle （Gradle 9.6 废弃了隐式从根项目查找）。
交换默认 ProGuard 文件名，迁移 core-ktx 到 androidx.core:core 1.19.0+，丢弃独立 Kotlin Gradle 插件使用，移除 jcenter().

您可以在 diff hunks 中阅读更新到 9.0 Android 部分并在分支上应用相同的清理，然后将 Capacitor 版本号升级

CLI: `cap run --url`

Capacitor 9 将合并 live-reload host/port/https flags 为一个参数。 --url 而不是:

bunx cap run android -l --host 192.168.1.181 --port 5173

传入开发服务器打印的 URL:

bunx cap run android --url http://192.168.1.181:5173/

更新脚本和 README snipets 以避免升级后肌肉记忆与新 CLI 冲突。

官方插件：push 和 splash 的注意事项

在生产应用中经常出现的两个用户界面变化是：

推送通知 (iOS): 已弃用的 alert presentation 选项已被移除。请使用 banner 和/或 list 在您的 presentation 选项中。

启动屏幕 (Android): Default launchFadeOutDuration 从 200 ms 到 0. 如果您依赖于淡入隐藏首次绘制的闪烁，设置 launchFadeOutDuration: 200 显式地 capacitor.config 直到您调整您的启动 UI。

扫描插件部分在 9.0 更新指南中

AndroidX 和 Google Play Services 版本升级与官方插件的关联

如果您发布 Capacitor 插件，它们将在 Capacitor 8 中被使用。 and 准备 Cap 9-ready code, 重点关注 废弃 API 的移除,而不是关注 Cap-9-only 包装更改。

在 Cap 8 还支持期间安全进行的操作:

替换 @NativePlugin 用 @CapacitorPlugin 并迁移遗留的权限/活动结果 API 到 @PermissionCallback / @ActivityCallback 模式（参见插件 9.0 指南表格）。
移除 PluginCall.hasOption, Plugin.getConfigValue,旧 CapConfig 构造器和 getter, PluginCall.save() / isSaved(), 和其他 Java 删除项，详见 “code 中的 Breaking changes”。
在 iOS 上，停止使用 CAPBridge 兼容性类和已弃用的 CAPBridgeProtocol 助手；使用 ApplicationDelegateProxy类型的 PluginCall 访问器和桥接属性，从迁移表中获取。
运行 bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

兼容性类和已弃用的 Cordova 助手；使用 Package.swift while you still support Capacitor 8. Cap 8 项目预期在您的插件基于 SPM 时会依赖该依赖项；提前删除它会破坏仍在使用 8 的消费者。处理 可选 Cordova / 删除不条件 Cordova 产品 作为 Capacitor 仅限 9 的 发布线 (或明确文档为 Cap 9+ 的 semver 主版本)，在您停止支持 Cap 8 时 — 如插件指南所述，而不是 Cap 8 行的预备工作。

同样的规则适用于 capacitor-swift-pm 升级 9.0.0-alpha.x 到 Package.swift上下文:实时更新产品页面。角色:短 UI 标签或导航项。消息键 `live_update_dynamic_label_to` (实时更新动态标签到)。

Capgo 实时更新和原生 Cap 9 商店构建

Capgo 提供 web 包 updates over the air; the native shell still comes from the App Store and Google Play. When you move your app to Capacitor 9:

发布 至少有一个商店构建 在Capacitor中编译了9个原生项目（iOS和Android）。该二进制文件确定了原生基线Capgo频道的目标。
只有在用户手中有该构建后，您才能依赖Cap 9 WebView和插件行为测试的OTA包。
将生产通道设置为 metadata 并上传匹配Cap 9包到每个通道中 --auto-min-update-version。对于该有意的原生基线上传 忽略 --fail-on-incompatible (原生包应该改变)。保持 --fail-on-incompatible 并 --auto-min-update-version 每日 OTA 上传后。参见原生 + OTA 通道工作流.
确保通道和 semver 规则保持一致，以免推送一个假设 Cap 9 API 将在仍在运行旧版原生 shell 的设备上推送的包

如果您使用 Capgo 构建或您的 CI、刷新代理之前在 Cap 9 商店发布之前，管道必须与用户安装的匹配： macOS 运行 Node 24+ 和 Xcode 27+; Linux runners 需要 Node 24+ 和 host Android 工具，保持与 AGP 9.2.1 / Gradle 9.5.1 (Xcode 只在 macOS 上可用).

建议的操作顺序

升级安装的工具 在 CI 主机和开发机器上升级到更高的版本（Node，Xcode，Android Studio，JDK）。不要升级 Cap 8 应用的 AGP 依赖项，Gradle 包装器或其他 Android 项目文件到 Cap 9 值，直到 bunx cap migrate —— 这些项目更改属于迁移步骤。
修复过时的本机 API 在应用程序 code 和插件（尤其是自定义 AppDelegate URL 处理和 Android 桥使用）中。
清洁 Android Gradle 文件和脚本（gradle.properties，ProGuard 默认值（ --url 在开发脚本中）。
审计 Cordova 使用在应用级别；不要改变 Cordova 插件 SPM Cordova 产品，直到 Cap 9-only 发布。
当 Cap 9 GA（或您接受 next）时，运行 bun add -d @capacitor/cli@next (或 @latest ），然后 bunx cap migrate，并遵循升级到 9.0.
发布 Cap 9 原生构建 将其发布到商店，然后恢复或扩展 Capgo OTA 运行时更新的匹配频道。