capacitor-app-upgrade-v7-to-v8

用途

本技能用于把 Capacitor 7 应用升级到 Capacitor 8（当前稳定线为 8.5.x）。权威依据为 https://capacitorjs.com/docs/updating/8-0。

适用时机：

package.json 中 @capacitor/core 为 7.x，用户希望升级到 8.x。
升级到 8 后出现以下问题：内容位于 Android 状态栏/导航栏之下（edge-to-edge）、找不到 bridge_layout_main、Gradle “space-assignment syntax” 弃用警告、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。

主要能力

通过 npx cap migrate 自动迁移：安装 ^8.0.0 包、将 iOS 目标/Podfile 提升到 15.0、运行 cap sync、在 configChanges 中加入 density、升级 Gradle wrapper 与 Gradle 文件，并输出破坏性变更。
处理配置变更：移除 android.adjustMarginsForEdgeToEdge，改用 System Bars 核心插件与 CSS env(safe-area-inset-*) 处理 insets；iOS appendUserAgent 不再添加两个额外空格，若服务器解析旧 UA，仅在 ios.appendUserAgent 前加一个空格（不要加在根键，根键也会影响 Android）。
iOS 调整：在 Project 及每个 Target 设置 iOS Deployment Target = 15.0；CocoaPods 项目在 Podfile 中写 platform :ios, '15.0'；删除自行发布 CAPBridgeViewController 通知的应用扩展，避免监听器触发两次。
Android 调整：按 references/android.md 处理 variables、= 赋值语法、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。
插件更新：将 @capacitor/* 插件更新到 ^8.0.0，社区插件更新到其 v8 版本，并应用 references/plugins.md。
CLI 说明：npx cap add ios 现在生成 SPM 项目；已有 CocoaPods 应用不受影响，若重新添加时保留 Pods 可使用 npx cap add ios --packagemanager CocoaPods。CocoaPods Trunk 将变为只读（预计 2026 年 12 月 2 日），因此建议升级后执行 cocoapods-to-spm。

使用方式

前置检查（最低要求）：

Node.js 22+（建议最新 LTS）
Xcode 26.0+
iOS deployment target 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

步骤：

从快照确认当前为 7.x。告知用户 minSdk 24 与 iOS 15 会放弃更旧设备。
运行自动迁移（latest 解析为最新 8.x）：

npm i -D @capacitor/cli@latest
npx cap migrate            # CI 中加 --noprompt，非 npm 时加 --packagemanager pnpm|yarn

完成其报告为失败的每一步；结束时输出 “Migration to Capacitor <v> is complete” 或 “... is incomplete”。查看日志消息获取更多信息。 3. 配置（capacitor.config.*）：移除 android.adjustMarginsForEdgeToEdge；处理 iOS appendUserAgent。 4. iOS：设置部署目标 15.0；删除重复发布通知的扩展。 5. Android：应用 references/android.md；重命名 bridge_layout_main。 6. 更新插件到 ^8.0.0 及社区插件 v8 版本。 7. 运行验证。

8.x 之后的必需步骤：

Xcode 27 要求 iOS UIScene 生命周期。Capacitor 8.5 已采用（SceneDelegate、UIApplicationSceneManifest）。升级后、用 Xcode 27 构建前，运行技能 capacitor-uiscene-migration。采用场景后，AppDelegate 的 application(_:open:options:)、continue userActivity 以及前台/后台生命周期回调将不再触发；深链与自定义 AppDelegate 代码必须迁移到场景委托。
然后运行 capacitor-app-upgrade-v8-to-v9（Capacitor 9 在 next 标签，尚未 GA）。

验证命令：

grep -rn "adjustMarginsForEdgeToEdge\|bundledWebRuntime" capacitor.config.*   # 期望无结果
grep -rn "bridge_layout_main" android/app/src src/ | grep -v capacitor_bridge   # 期望无结果
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   # 期望无结果
grep -n "configChanges" android/app/src/main/AndroidManifest.xml              # 包含 density
npx cap sync
cd android && ./gradlew assembleDebug --warning-mode all

在 Xcode 26+ 构建 iOS 并在设备上运行。在 Android 15+/16 上检查内容未位于状态栏或导航栏之下。

适用场景

需要把 Capacitor 7 应用迁移到 8.x 的移动应用项目。
升级后遇到 edge-to-edge 布局、资源布局名、Gradle 语法、Kotlin 编译、Geolocation 等兼容性问题。
需要按官方清单逐项核对升级结果。

限制

仅适用于 Capacitor 7.x 起点；6.x 需先升级到 7，已在 8.x 需转向其他技能。
需要满足 Node 22+、Xcode 26+、JDK 21、Android Studio Otter 2025.2.1+ 等前置条件。
自动迁移可能部分步骤失败，需按日志手动完成。
升级到 8.x 后，若使用 Xcode 27，还需额外完成 UIScene 迁移。
资料未提供收费、价格、平台支持范围或效果保证等信息。

技能介绍

用途

主要能力

使用方式

适用场景

限制