跳转至正文
Capacitor

为 Capacitor 9 做准备:App 和插件团队现在能做什么

Capacitor 9 对 Node、Xcode、Android Gradle 以及已弃用的原生 API 提出了更高要求。以下是如何在切换到该版本前,基于 Capacitor 8 做好准备的指南,包括 Cordova 可选同步、CLI 实时重载以及 Capgo OTA 商店构建。

为 Capacitor 9 做准备:App 和插件团队现在能做什么 Capgo 博客插图

Capacitor 9 已发布在 next dist-tag 上,目前正朝着正式版推进。你无需在 alpha 发布当天就升级 App,但可以参考 官方 Capacitor 9 更新指南 以及 插件更新指南 已经明确列出了值得尽早处理的工具链最低版本要求和 API 移除项。

本文是一份 准备 清单:你可以在 Capacitor 8(或某个分支)上完成的工作,以便最终的 bunx cap migrate 迁移过程变得平淡无奇,而不是痛苦不堪。当你准备好切换时,请逐行遵循上述 Ionic 指南。

工具链和平台最低要求(应用)

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

领域 Capacitor 9 要求
Node.js 24+ (推荐最新 LTS 版本;npm 11 附带 Node 24)
Xcode 的 Mac 27+
iOS 部署目标 16.0+
Android Studio 中的错误日志 2026.1.1+
Android Gradle 插件 (AGP) 9.2.1
Gradle wrapper 9.5.1

如果你仍在 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 的坑

生产应用中经常会出现两个面向用户的变更:

推送通知(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 8

如果您发布在 Capacitor 8 上使用的 Capacitor 插件 以及 想让 code 适配 Cap 9,重点放在 移除已弃用的 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 期间。 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:这应该放在 Capacitor 9 主版本中,而不是兼容 Capacitor 8 的发布版本。

Capgo Live Updates 与 Cap 9 原生商店构建

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 上传。详见 Native + OTA 渠道工作流.
  4. 保持渠道和 semver 规则一致,避免将依赖 Cap 9 API 的 bundle 推送到仍运行旧版 native shell 的设备上。

如果你使用 Capgo 构建 或您自己的 CI,刷新 agents 在……之前 Cap 9 商店发布版,让 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 桥接的使用)。
  3. 清理 Android Gradle 文件和脚本(gradle.properties,ProGuard 默认设置, --url 在开发脚本中)。
  4. 审计 Cordova 在应用层面的使用情况;在 Cap 9 专属版本发布之前,不要更改插件 SPM Cordova 产品。
  5. 当 Cap 9 正式发布(或当你接受 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 的团队。

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。