capacitor-app-upgrade-v8-to-v9

Capacitor 应用从 v8 升级到 v9

Capacitor 9 目前是预发布版本（截至 2026 年 10 月，使用 next dist-tag，版本为 9.0.0-alpha.x）。请使用 @next 安装；待 9.0.0 正式发布后，改用 @latest / ^9.0.0。升级生产应用前，请告知用户该版本尚未正式发布，并在分支上操作。

权威来源：https://capacitorjs.com/docs/updating/9-0

适用场景

符合以下情况时触发：

• 应用使用 @capacitor/core 8.x，且用户想升级到 Capacitor 9
• Capacitor 8 应用迁移到 Xcode 27 / Swift 6、AGP 9 或 Gradle 9 后出现构建错误
• npx cap run -l --host ... 不再起作用（已由 --url 取代）
• iOS 上推送通知的 presentationOptions: ['alert'] 不再显示横幅
• 不含 Cordova 插件的应用升级后，因 CapacitorCordova / com.getcapacitor.cordova 引用而失败

以下情况请勿使用：

• 应用仍使用 7 或更早版本 -> 使用 capacitor-app-upgrades（依次升级各主版本）
• 仅需完成 8.4 -> 8.5 的 UIScene 步骤 -> 使用 capacitor-uiscene-migration
• 插件库仓库 -> 使用 capacitor-plugin-upgrade-v8-to-v9
• 从 CocoaPods 迁移到 SPM -> 使用 cocoapods-to-spm（推荐，作为单独步骤）

当前项目快照

!node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}out.push('node='+process.version);const p='ios/App/App/';out.push('ios.SceneDelegate='+fs.existsSync(p+'SceneDelegate.swift'));out.push('ios.Podfile='+fs.existsSync('ios/App/Podfile'));console.log(out.sort().join('\n'))"

操作步骤

1. 升级前检查（任一项不符合时停止并报告）

node --version                     # must be >= 24
xcodebuild -version                # must be Xcode 27+
java -version                      # use the JDK bundled with Android Studio 2026.1.1+
grep -c UIApplicationSceneManifest ios/App/App/Info.plist
git status --short                 # clean tree, so the migration diff is reviewable

• Node < 24 或 Xcode < 27：请用户先升级工具链。
• 没有场景清单或没有 SceneDelegate.swift：应用尚未采用 UIScene。先在 8.5 上运行 capacitor-uiscene-migration 技能并验证，然后再返回此处。一次性完成这两个步骤会让深层链接出错时难以判断问题出在哪一步。
• 迁移前盘点原生自定义内容：自定义的 AppDelegate/SceneDelegate 代码、自定义 CAPBridgeViewController 子类、ios/App/App 或 android/app/src 中的本地插件、variables.gradle 中的额外变量、Cordova 插件（npx cap ls）。

2. 软件包与自动迁移

npm i -D @capacitor/cli@next
npx cap migrate

cap migrate 会更新依赖项和符合模板结构的原生文件，并列出无法自动处理的内容。该工具不适用于 monorepo；此类项目请手动迁移。然后将所有其他 @capacitor/* 软件包升级到 @next（官方插件也已发布 9.0.0），并检查 Capgo/第三方插件是否有兼容 Capacitor 9 的版本（npm view <pkg> peerDependencies）。

3. 手动检查清单（逐项验证，即使 migrate 报告成功也不例外）

• iOS -> references/ios.md：Xcode 27、pbxproj + Podfile 中的 iOS 16.0、@main、移除应用代码中的 CAPBridge/bridge API、建议使用 SPM。
• Android -> references/android.md：清理 gradle.properties、设置 variables.gradle 中的值、移除 targetSdkVersion、proguard-android-optimize.txt、显式的 rootProject.ext 定义、core-ktx、移除 Kotlin 插件、jcenter()、AGP 9.2.1、Gradle 9.5.1、google-services 4.5.0。
• 插件、CLI、配置 -> references/plugins-and-cli.md：更新官方插件变量、推送通知的 alert、启动屏的 launchFadeOutDuration、cap run --url、Cordova 运行时现为可选。

4. 同步、构建与验证

运行 npx cap sync，然后完成 references/verification.md 中的所有检查：搜索残留符号、构建两个原生平台、检查设备。按平台分别报告结果。

陷阱

• 在 gradle.properties 中保留 android.builtInKotlin=false 或 android.sdk.defaultTargetSdkToCompileSdkIfUnset=false（AGP Upgrade Assistant 会写入这些配置）会导致构建失败。删除整个 AGP 8 兼容性代码块。
• 即使设置了 minifyEnabled false，proguard-android.txt 也会在配置阶段失败。
• 在 AGP 9 内置 Kotlin 的情况下仍保留 apply plugin: 'kotlin-android' 会导致重复插件错误，本地插件模块中也一样。
• 不含任何 Cordova 插件的应用不再获得 CapacitorCordova / capacitor-cordova-android。导入这些符号的原生代码将无法编译，也没有可强制包含它们的标志。
• 旧版 UIScene 的 AppDelegate 代码（CAPBridge.handleOpenUrl、application(_:open:) 自定义逻辑）既无法编译，也不会被调用。将其移至 SceneDelegate。
• CocoaPods Trunk 预计将于 2026 年 12 月 2 日转为只读。升级成功后，再提供 cocoapods-to-spm。

错误处理

错误	修复方法
'@UIApplicationMain' is deprecated（Swift 6 模式下的错误）	替换为 @main
Cannot find 'CAPBridge' in scope	使用 ApplicationDelegateProxy.shared API（references/ios.md）
Could not find method jcenter()	在每个 build.gradle（包括本地插件）中替换为 mavenCentral()
配置失败，提示 proguard-android.txt	使用 proguard-android-optimize.txt
Kotlin 插件已应用／插件 org.jetbrains.kotlin.android 重复	移除 kotlin-android、kotlin-gradle-plugin classpath、kotlin-stdlib
重复类 androidx.core.*（core-ktx）	移除旧版 core-ktx，依赖 androidx.core:core:1.19.0
Could not get unknown property 'androidxAppCompatVersion'	在 app/build.gradle 顶部添加 def x = rootProject.ext.x
库模块之间的命名空间冲突	插件保留了脚手架／分叉版本的 namespace；更新该插件或报告此问题
cap run 出现 error: unknown option '-l'	npx cap run <platform> --url http://<ip>:<port>
npm ERR! engine／Node 版本错误	Node 24+

参考资料

仅在涉及相应主题时加载参考资料。

文件	加载时机
references/ios.md	任何 iOS 步骤或 iOS 构建错误
references/android.md	任何 Android／Gradle 步骤或构建错误
references/plugins-and-cli.md	官方插件行为变更、实时重载、Cordova 插件
references/verification.md	同步后：grep、构建、设备检查清单

相关技能：capacitor-uiscene-migration、capacitor-app-upgrades、capacitor-plugin-upgrade-v8-to-v9、cocoapods-to-spm、capacitor-push-notifications、capacitor-splash-screen。