capacitor-app-upgrade-v7-to-v8

Capacitor 应用从 v7 升级到 v8

将 Capacitor 7 应用升级到 Capacitor 8（当前稳定版本线：8.5.x）。权威信息来源：https://capacitorjs.com/docs/updating/8-0

适用场景

• 以下快照中的 @capacitor/core 为 7.x，且用户希望升级到 8.x。
• 升级到 8 后，遇到 Android 状态栏/导航栏下方的内容（边到边）、找不到 bridge_layout_main、Gradle“空格赋值语法”弃用警告、Kotlin 2 kotlinOptions 错误或 Geolocation 超时。
• 用户要求提供精确的 7 -> 8 检查清单。

请勿使用：

• 应用版本为 6.x -> 先使用 capacitor-app-upgrade-v6-to-v7。规划跨多个版本的升级 -> capacitor-app-upgrades。
• 应用已是 8.x -> 使用 capacitor-uiscene-migration（8.5 场景生命周期），然后使用 capacitor-app-upgrade-v8-to-v9。
• 插件库升级 -> 使用 capacitor-plugin-upgrade-v7-to-v8。
• 从 CocoaPods 迁移到 SPM -> 使用 cocoapods-to-spm。

实时项目快照

package.json 中当前的 Capacitor 软件包： !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)}}console.log(out.sort().join('\n'))"

参考资料

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

文件	加载时机
references/android.md	编辑 variables.gradle、Gradle 语法、wrapper、manifest、Kotlin 或边到边时
references/plugins.md	应用使用官方 @capacitor/* 插件（Geolocation、Screen Orientation、Barcode Scanner、Status Bar 等）时

升级前检查

工具	Capacitor 8 的最低要求
Node.js	22+（建议使用最新 LTS）
Xcode	26.0+
iOS 部署目标	15.0
Android Studio	Otter 2025.2.1+
Java（Gradle JDK）	21
AGP / Gradle	8.13.0 / 8.14.3
Android SDK	minSdk 24，compileSdk 36，targetSdk 36
Kotlin（如使用）	2.2.20

node -v && xcodebuild -version && java -version
git status --short
grep -rn "adjustMarginsForEdgeToEdge\|appendUserAgent" capacitor.config.*
grep -rn "bridge_layout_main" android/ src/ 2>/dev/null

流程

1. 从快照确认版本为 7.x。告知用户，minSdk 24 和 iOS 15 会停止支持较旧设备。

2. 运行自动迁移（latest 会解析为最新的 8.x）：

   npm i -D @capacitor/cli@latest
   npx cap migrate            # add --noprompt in CI, --packagemanager pnpm|yarn if not npm
   

   它会安装 ^8.0.0 软件包，将 iOS 目标版本／Podfile 提升至 15.0，运行 cap sync，将 density 添加到 configChanges，升级 Gradle wrapper 和 Gradle 文件，并写入破坏性变更。完成报告为失败的每个步骤；结束时会显示 Migration to Capacitor <v> is complete 或 ... is incomplete. Check the log messages for more information.

3. 配置（capacitor.config.*）：

   • android.adjustMarginsForEdgeToEdge 已移除。请移除该项，然后使用 System Bars 核心插件和 CSS env(safe-area-inset-*) 处理内边距（参见 references/android.md 和 safe-area-handling）。
   • iOS appendUserAgent 不再添加两个额外空格。如果服务器会解析旧版 UA，只在 ios.appendUserAgent 前添加一个空格（不要添加到根键；根键也会影响 Android）。

4. iOS：

   • 在项目和每个目标上将 iOS Deployment Target = 15.0；在 Podfile（CocoaPods 项目）中设置 platform :ios, '15.0'。
   • Capacitor 现在会为 viewDidAppear 和 viewWillTransition 发送 CAPBridgeViewController 通知。删除任何自行发送这些通知的应用扩展，否则监听器会触发两次。

5. Android：应用 references/android.md（变量、= 赋值语法、AGP 8.13.0、Gradle 8.14.3、google-services 4.4.4、Kotlin 2.2.20、density）。将任何 bridge_layout_main 引用改为 capacitor_bridge_layout_main。

6. 将 @capacitor/* 插件更新到 ^8.0.0，将社区插件更新到各自的 v8 版本。应用 references/plugins.md。

7. CLI 说明：现在 npx cap add ios 会生成 SPM 项目。现有 CocoaPods 应用不受影响；若重新添加时要继续使用 Pods，请运行 npx cap add ios --packagemanager CocoaPods。CocoaPods Trunk 将变为只读（预计于 2026 年 12 月 2 日），因此建议在升级后使用 cocoapods-to-spm。

8. 运行验证。

升级到 8.x 后：接下来的必做步骤

• Xcode 27 要求使用 iOS UIScene 生命周期。Capacitor 8.5 已采用该生命周期（SceneDelegate、UIApplicationSceneManifest）。升级后，在使用 Xcode 27 构建之前运行技能 capacitor-uiscene-migration。采用 scenes 后，AppDelegate 的 application(_:open:options:)、continue userActivity 和前台／后台生命周期回调将不再触发；深层链接和自定义 AppDelegate 代码必须移至 scene delegate。
• 然后运行 capacitor-app-upgrade-v8-to-v9（Capacitor 9 当前位于 next 标签，尚未正式发布）。

验证

grep -rn "adjustMarginsForEdgeToEdge\|bundledWebRuntime" capacitor.config.*   # expect none
grep -rn "bridge_layout_main" android/app/src src/ | grep -v capacitor_bridge   # expect none
grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u   # 15.0
grep -n "gradle:8.13.0\|google-services:4.4.4" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties    # gradle-8.14.3
grep -n "SdkVersion" android/variables.gradle                                 # 24 / 36 / 36
grep -nE "^\s*(namespace|compileSdk|ignoreAssetsPattern) [^=]" android/app/build.gradle   # expect none
grep -n "configChanges" android/app/src/main/AndroidManifest.xml              # includes density
npx cap sync
cd android && ./gradlew assembleDebug --warning-mode all

使用 Xcode 26+ 构建 iOS 并在设备上运行。在 Android 15+/16 上检查内容是否被状态栏或导航栏遮挡。

错误处理

错误	修复方法
Migrate can only be used on Capacitor 7, please use the CLI in Capacitor 7 to upgrade to 7 first	先运行 capacitor-app-upgrade-v6-to-v7。
Capacitor 8 requires JDK 21 or higher. Some steps may fail.	将 Gradle JDK 设置为 21。
Unable to add 'density' to 'android:configChanges' in <file>. Try adding it manually	将 |density 添加到主 Activity 的 configChanges。
gradle wrapper files were not updated	将 distributionUrl 编辑为 gradle-8.14.3-all.zip，然后运行 cd android && ./gradlew wrapper。
Unable to find "<text>" in <file>. Try updating it manually	应用 references/android.md 中的差异。
Properties should be assigned using the 'propName = value' syntax（Gradle 弃用提示）	在属性赋值中添加 =。
R.layout.bridge_layout_main 上出现 cannot find symbol（或 AAPT 报错 resource layout/bridge_layout_main ... not found）	使用 capacitor_bridge_layout_main。
Kotlin：出现 kotlinOptions / kotlin-android-extensions 错误	改用 kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }；用视图绑定替换合成属性，用 kotlin-parcelize 替换 parcelize。