为 Capacitor 9 做准备：App 与插件团队现在可以做些什么

Capacitor 9 已在以下版本可用： next dist-tag，目前正向正式版过渡。你无需在 alpha 版本发布当天立即升级 App，但可以参考 官方 Capacitor 9 更新指南 以及 插件更新指南 已经列出了值得尽早处理的工具链缺陷和 API 移除项。

本文是一份 准备 清单：你可以在 Capacitor 8（或在分支上）完成这些工作，从而让最终的 bunx cap migrate 迁移过程变得轻松而非痛苦。准备好切换时，请逐行遵循上方链接的 Ionic 指南。

工具链与平台底线 (App)

请围绕以下最低要求规划你的 CI、本地机器和商店流水线：

如果你在 iOS 上仍使用 Capacitor 8.4 或更早版本，还需要 UIScene 生命周期 在 Cap 9 之前的 Capacitor 8.5 更新中已实现 —— Xcode 27 需要它。已升级至 8.5 的应用可以跳过此步骤。

在 iOS 上，Swift 6 (配合 Xcode 27) 会拒绝 @UIApplicationMain; 升级时，请将其替换为 @main 中的 AppDelegate.swift ，具体请参考官方指南。

App 同步时的 Cordova（并非插件准备步骤）

在 Capacitor 9 中，Cordova 兼容层 仅当以下情况时才会接入你的 App： cap sync 检测到已安装的 Cordova 插件。没有插件时，Android 会移除多余的 Gradle 模块；iOS 则不再向 CapacitorCordova Podfile 添加内容，或 Package.swift 在没有插件时停止相关操作。

这是 App 层级的 行为变化，会在你升级后出现。如果你仍在使用 Cap 8，无需提前从模板中移除 Cordova。但请检查是否有任何 自定义原生 code （你自己的或 fork 的插件）在项目中没有实际 Cordova 插件的情况下导入了 Cordova 符号 —— 一旦可选的 Cordova 接入生效，这些引用就会失效。

Android： gradle.properties 以及 AGP 9 的默认设置

AGP Upgrade Assistant 通常会写入显式的 gradle.properties flags 以保持 AGP 8 的构建行为。Capacitor 9 应用应当 移除 这些条目，而不是继续沿用：大多数会在 AGP 10 之前弃用，部分还会导致 Cap 9 构建失败（例如 android.builtInKotlin=false 会禁用 AGP 9 内置的 Kotlin 支持，并且 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false 会让 AGP 无法推断 targetSdkVersion).

迁移时，还需要：

• 提升 variables.gradle 最低版本要求（compile/target 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 plugin，并移除 jcenter().

你可以在 升级到 9.0 的 Android 部分查看 diff hunks，并在升级 Capacitor 版本前，先在分支上做同样的清理。

CLI： cap run --url

Capacitor 9 将 live-reload 的 host/port/https 标志合并为单个 --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 代码片段，以免升级后因肌肉记忆导致与新的 CLI 冲突。

官方插件：Push 和 Splash 的注意事项

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

Push Notifications (iOS)： 已弃用的 alert presentation 选项已被移除。请使用 banner 和/或 list 在你的 presentation 选项中。

启动页 (Android): 默认 launchFadeOutDuration 从 200 ms 变为 0。如果你之前依赖淡出效果来掩盖首次渲染的闪烁，请在 launchFadeOutDuration: 200 中显式设置 capacitor.config ，直到你调整好启动 UI。

请查阅 9.0 更新指南 中的插件章节，了解你所使用的官方插件中 AndroidX 和 Google Play Services 的版本升级情况。

插件维护者：请在 Cap 8 环境下为 Cap 9 做准备，同时确保不破坏 Cap 8 的兼容性

如果你发布的 Capacitor 插件被 Capacitor 8 使用 以及 想要为 Cap 9 做好 code 准备，请专注于 移除已弃用的 API，而不是仅针对 Cap 9 的打包变更。

在 Cap 8 仍受支持期间可以安全进行：

• 替换 @NativePlugin 配合 @CapacitorPlugin 并将旧版权限 / activity-result API 迁移至 @PermissionCallback / @ActivityCallback 新模式（请参阅 plugin 9.0 指南 表格）。
• 移除 PluginCall.hasOption, Plugin.getConfigValue，旧的 CapConfig 构造函数和 getter, PluginCall.save() / isSaved()，以及“code 的破坏性变更”中列出的其他 Java 移除项。
• 在 iOS 上，停止使用 CAPBridge 兼容类和已弃用的 CAPBridgeProtocol 辅助函数；请使用 ApplicationDelegateProxy，带类型的 PluginCall 访问器以及迁移表中的 bridge 属性。
• 运行 bunx @capacitor/plugin-migration-v8-to-v9@latest 在一个分支上进行，并仅保留那些仍能通过 Cap 8 peer dependencies 编译的 API 编辑，直到你发布 Cap 9 的大版本。

不要移除 Cordova 插件中的 SPM product Package.swift 只要你还在支持 Capacitor 8。 当你的插件基于 SPM 时，Cap 8 项目会依赖该项；过早移除会导致仍在使用 8 的用户无法使用。请将 可选的 Cordova / 移除无条件 Cordova 产品 视为 Capacitor 9 专用 发布分支（或明确记录为 Cap 9+ 的 semver 主版本），在停止支持 Cap 8 后进行——如插件指南所述，而不是在 Cap 8 分支上做准备工作。

同样的原则也适用于升级 capacitor-swift-pm 改为 9.0.0-alpha.x 中的 Package.swift：这属于 Cap 9 的重大更新，而不应出现在兼容 Cap 8 的版本中。

Capgo live updates 和原生 Cap 9 Store 构建

Capgo 提供 Web Bundle 空中下载 (OTA) 更新；原生壳程序仍来自 App Store 和 Google Play。当你将应用迁移到 Capacitor 9 时：

1. 发布 至少需要一个商店版本 基于 Capacitor 9 原生项目 (iOS 和 Android) 编译。该二进制文件将确立 Capgo 通道所针对的原生基线。
2. 只有在该版本已交付给用户后，你才应该依赖针对 Cap 9 WebView 和插件行为测试过的 OTA bundle。
3. 将生产环境通道设置为 metadata 策略，并将匹配的 Cap 9 bundle 上传到每个通道，并使用 --auto-min-update-version。对于这种有意的原生基线上传， 请忽略 --fail-on-incompatible （原生包通常会发生变化）。请保留 --fail-on-incompatible 以及 --auto-min-update-version 之后不再需要频繁进行 OTA upload。查看 Native + OTA channel 工作流.
4. 保持 channel 与 semver 规则一致，避免将依赖 Cap 9 API 的 bundle 推送到仍在使用旧版 native shell 的设备上。

如果你使用 Capgo 构建 或你自己的 CI，请更新 agent 在……之前 以匹配 Cap 9 的 store 版本，确保 pipeline 与用户安装的版本一致： macOS runners 需要 Node 24+ 以及 Xcode 27+; Linux runners 需要 Node 24+，宿主机上的 Android 工具链需与以下版本对齐： AGP 9.2.1 / Gradle 9.5.1 （Xcode 仅支持 macOS）。

建议操作顺序

1. 升级已安装的工具链 将 CI 主机和开发机上的工具（Node、Xcode、Android Studio、JDK）升级至上述最低版本。 切勿 在迁移步骤之前，将 Cap 8 应用的 AGP 依赖、Gradle wrapper 或其他 Android 项目文件升级到 Cap 9 的版本 bunx cap migrate — 这些项目变更属于迁移步骤。
2. 修复已弃用的原生 API 在应用 code 和插件中（尤其是自定义 AppDelegate URL 处理和 Android bridge 的使用）。
3. 清理 Android Gradle 文件和脚本（gradle.properties，ProGuard 默认设置， --url 在 dev 脚本中）。
4. 审计 Cordova 在应用层级的用法；在 Cap 9 专属版本发布前，请勿更改插件 SPM Cordova 产品。
5. 当 Cap 9 进入 GA 阶段（或当你接受 next），运行 bun add -d @capacitor/cli@next (或 @latest 发布后），然后 bunx cap migrate，并遵循 升级到 9.0.
6. 发布 Cap 9 原生构建 到应用商店，然后在对应 channel 上恢复或扩大 Capgo OTA 发布。

Capacitor 9 主要是在“处理弃用项，并与现代 Android 和 Apple 工具链对齐”。在 Cap 8 上做这些工作，能让升级 diff 更小，也能让你的插件兼容今天仍在发布 8.x 的团队。