Capacitor 9 已经在 dist-tag 上发布，正在朝着广泛可用性迈进。您不必在 alpha 发布的那天就升级您的应用，但请阅读 Capacitor 9 的官方更新指南和插件更新指南，它们已经详细说明了需要早期处理的工具链版本和 Capacitor 的移除。 next __CAPGO_KEEP_0__ 9 Capacitor 9 并且 插件更新指南 已经详细说明了需要早期处理的工具链版本和 API 的移除。
本文是一份准备工作清单：您可以在 __CAPGO_KEEP_0__ 8 (或分支)上进行的工作，以便在切换到 __CAPGO_KEEP_0__ 9 时避免痛苦。切换时，请按照上面链接的 Ionic 指南逐步执行。 工具链和平台底线（应用） checklist: work you can do on Capacitor 8 (or on a branch) so the eventual bunx cap migrate __CAPGO_KEEP_0__ 9
__CAPGO_KEEP_0__ 9
__CAPGO_KEEP_0__ 9
| 区域 | Capacitor 9 的要求 |
|---|---|
| Node.js | 24+ (最新的 LTS 建议; npm 11 自带 Node 24) |
| Xcode | 27+ |
| iOS 部署目标 | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle 插件 (AGP) | 9.2.1 |
| Gradle 包装器 | 9.5.1 |
如果您仍在使用 Capacitor 8.4 或更早版本的 iOS， UI 场景生命周期 从 Capacitor 8.5 更新中获取工作 — Xcode 27 需要它。已经升级到 8.5 的应用程序可以跳过额外的步骤。
在 iOS 上，Swift 6（使用 Xcode 27）拒绝 @UIApplicationMain当您升级时，请将其替换为 @main 在 AppDelegate.swift 如官方指南所述
Cordova 在应用程序同步时间（不是插件预备步骤）
在 Capacitor 9 中，Cordova 兼容性层 仅在检测到安装的 Cordova 插件时 cap sync 为应用程序Android 在没有插件存在时会丢弃额外的 Gradle 模块； iOS 会停止添加 CapacitorCordova 到 Podfile 或 Package.swift 当没有插件存在时
这就是 app-level 升级后行为变化。您仍在Cap 8上时，不需要提前从模板中移除Cordova。请检查是否有任何 自定义本机code (您自己的或fork的插件)导入Cordova符号，而没有在项目中实际包含Cordova插件——这些引用将在Cordova编程应用时失败。
Android: gradle.properties 和AGP 9默认值
AGP升级助手经常写入明确的 gradle.properties 标志，以便构建保留AGP 8行为。Capacitor 9应用应该 移除 这些条目，而不是将它们保留下来：大多数在AGP 10之前就被弃用了，某些会破坏Cap 9构建（例如 android.builtInKotlin=false 禁用AGP 9捆绑的Kotlin支持，并 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false 阻止AGP推断 targetSdkVersion).
When you migrate, also expect to:
- Bump
variables.gradleminimums (compile/target SDK 37,26, updated AndroidX versions — see the official doc).minSdkVersionRemove explicit - from the app
targetSdkVersionso AGP 9 can infer it frombuild.gradleDeclarecompileSdkVersion. - symbols at the top of
variables.gradle(Gradle 9.6 deprecates implicit lookup from the root project).app/build.gradleSwap default ProGuard file names, migrate - to
core-ktxLive Updateandroidx.core:core1.19.0+, 放弃独立 Kotlin Gradle 插件使用，并移除jcenter().
您可以在 diff hunks 中阅读 更新到 9.0 Android section and apply the same cleanups on a branch before bumping Capacitor versions.
CLI: cap run --url
Capacitor 9 合并 live-reload 主机/端口/HTTPS 标志到一个单独的 --url 参数。取而代之的是:
bunx cap run android -l --host 192.168.1.181 --port 5173将 URL 传递给开发服务器打印的 URL:
bunx cap run android --url http://192.168.1.181:5173/更新脚本和 README snipets 以避免肌肉记忆与新 CLI 的冲突。
官方插件：推送和启动屏幕的陷阱
在生产应用中经常出现的两个用户界面变化是：
推送通知（iOS）： 已废弃的 alert 呈现选项已移除。请使用 banner 和/或 list 在您的呈现选项中。
启动屏幕（Android）： 默认 launchFadeOutDuration 从 200毫秒变为。如果您依赖于淡入以隐藏首次绘制的闪烁，请在 launchFadeOutDuration: 200 中设置 capacitor.config ，直到您调整您的启动 UI。
扫描插件部分 9.0更新指南 针对AndroidX和Google Play Services版本升级与官方插件关联
插件维护者：在Cap 8上预备，不要破坏Cap 8
If you ship Capacitor plugins consumed on Capacitor 8 并 want Cap 9-ready code, focus on deprecated API removal过期
的移除
- ,而不是Cap-9-only的打包变化
@NativePlugin在Cap 8仍然支持的情况下安全进行的操作:@CapacitorPlugin替换为@PermissionCallback/@ActivityCallback模式（参见“ 插件9.0指南 ）表格）。 - 移除
PluginCall.hasOption,Plugin.getConfigValue，旧CapConfig构造函数和获取器,PluginCall.save()/isSaved()，以及Java中列出的其他破坏性更改“code”。 - 在iOS上，停止使用
CAPBridge兼容性类和已弃用的CAPBridgeProtocol助手；使用ApplicationDelegateProxy类型PluginCall访问器和桥接属性从迁移表中。 - 开始
bunx @capacitor/plugin-migration-v8-to-v9@latest在一个分支上运行，并只保留那些仍然可以编译并且依赖于Cap 8的API的修改，直到您发布Cap 9的重大更新。
不要移除 Cordova SPM产品 Package.swift while you still support Capacitor 8. 的 直到您停止支持Cap 8 — 如插件指南所述，而不是Cap 8线程的预备工作。 Cordova 同样的规则也适用于 升级 Capacitor 9-only release line (or a semver major explicitly documented as Cap 9+)
The same rule of thumb applies to bumping capacitor-swift-pm 到 9.0.0-alpha.x 在 Package.swift: 应该在 Cap 9 主版本中，而不是在兼容 Cap-8 的版本中。
Capgo 实时更新和原生 Cap 9 商店构建
Capgo 提供 网上包 通过无线电更新；原生壳仍然来自 App Store 和 Google Play。 当您将应用程序迁移到 Capacitor 9 时：
- Ship 至少有一个商店构建 编译为 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 Build __CAPGO_KEEP_0__ Build 或您的CI刷新代理之前 Cap 9 商店发布，因此管道与用户安装的匹配: macOS 运行器需要 Node 24+ 和 Xcode 27+; Linux 运行器需要 Node 24+ 和主机 Android 工具与 AGP 9.2.1 / Gradle 9.5.1 （Xcode 只在 macOS 上可用）。
建议的操作顺序
- 在 CI 主机和开发机器上升级安装的工具到 Node、Xcode、Android Studio 和 JDK 的楼层以上。 不要 升级 Node、Xcode、Android Studio 和 JDK 升级 Cap 8 应用程序的 AGP 依赖项、Gradle 包装器或其他 Android 项目文件到 Cap 9 值，直到
bunx cap migrate— 这些项目更改属于迁移步骤。 - 修复过时的本机 API 在应用程序 code 和插件（尤其是自定义
AppDelegateURL 处理和 Android 桥使用）中。 - 清理 Android Gradle 文件和脚本（
gradle.properties，ProGuard 默认值--url在开发脚本中）。 - 审计 Cordova 在应用程序级别使用；不要更改 Cap 9-only 发布的插件 SPM Cordova 产品。
- 当 Cap 9 GA (或当您接受
next，运行bun add -d @capacitor/cli@next（或”@latest发布后，然后bunx cap migrate更新到 9.0 发布 Cap 9 原生构建. - 到商店，然后恢复或扩展 __CAPGO_KEEP_0__ OTA 部署到匹配的频道。 Capgo 9 大部分是“清偿过时的功能并与现代 Android 和 Apple 工具链保持一致。”在 Cap 8 上完成该工作可以使升级差异小并且您的插件与仍在发布 8.x 的团队兼容。
Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.
