如何升级您的 Capacitor 应用程序到 Capacitor 8

要升级一个 Capacitor 应用到 Capacitor 8，请安装 Node.js 22+，Xcode 26+ 和 Android Studio Otter，更新 @capacitor/cli 到最新的 8.x，运行 bunx cap migrate然后修复迁移工具报告的任何问题。主要的破坏性更改是 iOS 15 作为最低部署目标，Android SDK 36（最低 SDK 24），AGP 8.13（Gradle 8.14.3），以及移除 adjustMarginsForEdgeToEdge 为了新版系统栏插件的支持。

本指南将逐步介绍自动升级路径、每个手动步骤以及升级后最常遇到的错误。如果您维护的是一个插件而不是一个应用，请阅读 如何升级您的Capacitor插件到Capacitor8 instead.

Capacitor 8 的需求概览

Check your toolchain before touching the project. Most failed upgrades are an old JDK, an old Xcode, or an old Node in CI, not the code.

Xcode 26 不仅是 Capacitor 的要求。自 2026 年 4 月 28 日起，App Store Connect 将拒绝使用旧 Xcode 构建的上传，因此您需要它。请参见 Apple 的 Xcode 26 对 Capacitor 应用程序的要求 __CAPGO_KEEP_0__ 应用

详细信息。

1. 开始之前
2. 确保应用程序在 Capacitor 7今天可以正常编译。升级一个破损的项目只会增加噪音。
3. 如果您正在使用 Capacitor 6 或更早版本，请先完成之前的重大更新。每个重大更新都有自己的迁移逻辑在 CLI。
4. 确保应用程序在 __CAPGO_KEEP_0__ 7 上构建。升级一个破碎的项目只会增加噪音。 bunx cap ls 如果您在 Capacitor 6 或更早版本上，则首先完成上一个主要版本。每个主要版本都有自己的迁移逻辑在 __CAPGO_KEEP_1__ 中。 peerDependencies 列出您的插件并检查每个插件是否支持 __CAPGO_KEEP_0__ 8 的最新版本。查看最新版本的

bun pm view @capgo/capacitor-updater peerDependencies

一个带有插件 @capacitor/core: ^7.0.0 作为其配对插件会安装时会显示警告并可能无法编译。 Capgo 插件遵循 Capacitor 的主要版本号，因此 @capgo/* 8.x 版本的目标是 Capacitor 8.

5. 更新本地和 CI 工具链：Node 22，Xcode 26，JDK 21，Android Studio Otter。在 GitHub Actions 中，固定一个带有 Xcode 26 的 macOS 镜像并使用 actions/setup-java with java-version: '21'.

选项 1：使用 cap migrate

CLI 提供了一个迁移命令来处理大部分工作。安装最新的 CLI，然后运行它：

bun add -D @capacitor/cli@latest
bunx cap migrate

The migrator asks whether it should install the new Capacitor packages and lets you pick npm, Yarn, pnpm or Bun. Pick Bun if your project has a bun.lock跳过提示 bunx cap migrate --noprompt.

它会为你做什么：

• 升级 @capacitor/core, @capacitor/ios, @capacitor/android 和官方 @capacitor/* 升级 Capacitor 应用到 Capacitor 8.x.
• 设置 IPHONEOS_DEPLOYMENT_TARGET = 15.0 在 Xcode 项目中和 platform :ios, '15.0' 在 Podfile 中。
• 更新 variables.gradlecontext kotlin_version.
• Adds density 升级 android:configChanges context AndroidManifest.xml.

Read the full output. When a step cannot be applied, for example because a file was customized, the CLI prints an error with the file name and continues. Those lines are your manual to-do list.

添加

bun run build
bunx cap sync

到

选项 2：手动升级

如果您的原生项目高度定制化，或者迁移工具跳过了步骤，请手动应用更改。这些与官方的__CAPGO_KEEP_0__8升级指南相匹配 更新Capacitor包.

更新npm包

bun add @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
bun add -D @capacitor/cli@latest

iOS：将部署目标提高到15.0

bun add @capacitor/app@latest @capacitor/splash-screen@latest @capacitor/status-bar@latest

在Xcode中，选择项目，打开

配置 , 查找iOS部署目标 在 部署 Deployment 并将其设置为 15.0。重复此过程，包括扩展。

如果应用仍使用 CocoaPods，则更新 ios/App/Podfile:

platform :ios, '15.0'

然后运行 bunx cap sync ios,它将 pod install 为您执行。

如果应用使用 SPM，则 CLI 将在每次同步时重生成 ios/App/CapApp-SPM/Package.swift ，并且将使用正确的平台版本和与您安装的 capacitor-swift-pm 版本完全匹配的版本。请勿手动编辑该文件。 @capacitor/iosiOS：移除自定义视图控制器通知

__CAPGO_KEEP_0__ 8 现在发出

Capacitor 8 现在输出 CAPBridgeViewController 用于 viewDidAppear 和 viewWillTransition Capacitor 8 的升级 .capacitorViewDidAppear or .capacitorViewWillTransition或

升级到 Android Studio 和 AGP

安装 Android Studio Otter 或更高版本，打开文件夹并运行 android 工具 > AGP 升级助手 . 选择 8.13.0 并运行所选步骤。 或直接编辑：或 android/build.gradle directly:

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
        classpath 'com.google.gms:google-services:4.4.4'
    }
}

And android/gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip

升级到 Android Studio 和 AGP variables.gradle

ext {
    minSdkVersion = 24
    compileSdkVersion = 36
    targetSdkVersion = 36
    androidxActivityVersion = '1.11.0'
    androidxAppCompatVersion = '1.7.1'
    androidxCoordinatorLayoutVersion = '1.3.0'
    androidxCoreVersion = '1.17.0'
    androidxFragmentVersion = '1.8.9'
    coreSplashScreenVersion = '1.2.0'
    androidxWebkitVersion = '1.14.0'
    junitVersion = '4.13.2'
    androidxJunitVersion = '1.3.0'
    androidxEspressoCoreVersion = '3.7.0'
    cordovaAndroidVersion = '14.0.1'
}

保持任何额外的变量，插件读取（例如 firebaseMessagingVersion官方插件升级到Capacitor 8包括 firebaseMessagingVersion = '25.0.1', androidxBrowserVersion = '1.9.0', androidxMaterialVersion = '1.13.0' 和 androidxExifInterfaceVersion = '1.4.1'.

Android：切换到 = 在Gradle文件中

Gradle弃用了空格赋值语法。它今天只会警告，但将在Gradle的未来版本中破坏，所以现在在 android/app/build.gradle:

android {
-    namespace "com.example.app"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.example.app"
+    compileSdk = rootProject.ext.compileSdkVersion
     defaultConfig {
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
         }
     }
}

方法调用，如 google() 或 mavenCentral() 如果您的应用模块使用Kotlin，请设置

Kotlin 2.x将旧 configChanges

Kotlin 2.x将旧 kotlin_version = '2.2.20'Kotlin 2.x将旧 kotlinOptions {} 将块转换为错误，因此移动 jvmTarget 到 kotlin { compilerOptions { ... } }.

然后添加 density 到主活动中，以便在显示密度发生变化（折叠屏幕、窗口大小调整、显示大小设置）时WebView不会重新创建：

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Android：桥接布局已更名

bridge_layout_main.xml 不再存在。如果您 MainActivity 或自定义片段引用 R.layout.bridge_layout_main，使用 R.layout.capacitor_bridge_layout_main.

边缘到边缘和新系统栏插件

这是最有可能在视觉上显示的变化。 Capacitor 8已删除 android.adjustMarginsForEdgeToEdge 并添加了一个核心系统栏插件。您不需要安装它，它随 @capacitor/core.

Android 15要求应用以SDK 35为目标，边缘到边缘，Android 16移除了SDK 36应用的优惠券。 Capacitor 8目标36，因此您的Web内容现在绘制在状态栏和导航栏后面，除非您处理边缘。

The plugin config lives under __CAPGO_KEEP_0__ plugins.SystemBars:

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  plugins: {
    SystemBars: {
      // 'css' (default) injects --safe-area-inset-* variables on Android
      // 'native' relies on env() and viewport-fit
      // 'disable' leaves inset handling entirely to you
      insetsHandling: 'css',
      initialViewportFitValueHint: 'cover',
    },
  },
};

export default config;

With css 或 nativeCapacitor live-update alternatives comparison page: viewport-fit=cover Capacitor live-update alternatives comparison page: env(safe-area-inset-*) values。 在较旧的WebViews中，Capacitor会填充WebView并将env值设为 0pxCapacitor live-update alternatives comparison page:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

Appflow comparison / migration marketing copy:

import { SystemBars, SystemBarsStyle, SystemBarType } from '@capacitor/core';

await SystemBars.setStyle({ style: SystemBarsStyle.Dark });
await SystemBars.hide({ bar: SystemBarType.NavigationBar });

Appflow comparison / migration marketing copy: Appflow comparison / migration marketing copy: 描述了 Capacitor 7 的选项，但该选项已在 8 中被删除。

Capawesome comparison page:

• appendUserAgent On iOS: Capacitor 7 添加了两个空格，Capacitor 8 添加了一个空格。如果您的服务器严格解析用户代理，请在前面添加一个空格 ios.appendUserAgent (不是根选项，也会影响 Android)
• 屏幕方向和条形码扫描: 在 Android 16+ 大屏幕上，屏幕方向锁定被忽略。通过 manifest 属性存在一个临时的 opt-out，但 Android 17 将其删除 android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY 地理位置
• Geolocation: timeout 在 Android 上获得了一个 watchPosition 状态栏 interval : 插件不再提供自己的
• 屏幕方向和条形码扫描屏幕方向和条形码扫描 CAPBridgeViewController notification 文件，自核心开始发出这些事件。
• 新 iOS 平台默认使用 SPM: bunx cap add ios 现在创建一个 SPM 项目。使用 --packagemanager CocoaPods 如果您需要旧模板，请参阅 了解如何使用 CocoaPods 与 Capacitor 8.

验证升级

在两个平台上运行此列表之前，确保已完成：

bunx cap doctor
bunx cap sync
bunx cap run ios
bunx cap run android

• cap doctor 显示核心、CLI、iOS 和 Android 的匹配 8.x 版本。
• 应用程序启动，启动屏幕隐藏，深度链接打开正确的屏幕。
• 状态栏和导航栏区域在 Android 15/16 设备和非凹版 iPhone 上看起来正确。
• 推送通知、相机、文件访问和任何具有本机权限的插件仍然工作。
• 发布构建（在 Xcode 中的存档， ./gradlew bundleRelease）成功，不仅仅是调试。

如果您不想在每台机器上维护 Xcode 26 和 JDK 21， Capgo 构建 context

安全升级到 Capacitor 8

A Capacitor major upgrade changes native code, so it has to go through the App Store and Google Play. Web bundles built after the upgrade may call plugin APIs that older binaries don’t have.

安全地升级应用程序 一个 Capgo 主要升级会改变本机 __CAPGO_KEEP_1__，因此必须通过 App Store 和 Google Play。升级后构建的 Web 包可能会调用旧版本二进制文件中没有的插件 API。, keep Capacitor 7 users and Capacitor 8 users apart until adoption catches up: bump your native version, upload new bundles to a channel used by the new binary, and run the __CAPGO_KEEP_0__ 实时更新 ，请确保 __CAPGO_KEEP_0__ 7 用户和 __CAPGO_KEEP_1__ 8 用户之间的隔离，直到采用率赶上：升级本机版本，上传新包到新二进制使用的频道，运行

bunx @capgo/cli@latest bundle compatibility

兼容性检查

Troubleshooting common Capacitor 8 升级错误

The engine "node" is incompatible CLI 升级后拒绝运行 您使用的 Node 版本为 20 或更早。请安装 Node 22 LTS，并更新 CI 镜像。

error: invalid source release: 21 在 Android 上 Gradle 使用 JDK 17。请将 Android Studio 配置为使用其内置的 JDK 21（设置 > 构建，执行和部署 > 构建工具 > Gradle > Gradle JDK)，并设置 JAVA_HOME 为命令行和 CI 构建使用 JDK 21。

Minimum supported Gradle version is 8.13. 您已更新 AGP，但未更新 wrapper。请将 wrapper 设置为 8.14.3。

Dependency ... requires libraries and applications that depend on it to compile against version 36. compileSdkVersion 仍然是 35。检查 variables.gradle 并检查任何硬编码 35 的插件。

Using 'kotlinOptions' ... is an error 或类似的 Kotlin DSL 错误。某个插件或您的应用模块仍然使用 kotlinOptions升级到 Capacitor 8 的应用程序 如何修复一个Capacitor插件).

Xcode: No such module 'Capacitor' Xcode: 升级后 App.xcworkspace, not App.xcodeproj，而不是 bunx cap sync ios，并重新运行 。对于 SPM，使用.

"X" plugin is not implemented on ios/android. 该插件未同步，或者它没有Capacitor 8 / SPM兼容的版本。运行 bunx cap sync 插件没有同步，或者它没有 __CAPGO_KEEP_0__ 8 / SPM 兼容的发布。运行

并阅读警告。 Capacitor iOS故障排除指南 和 Android故障排除指南. 修复Capacitor版本不符错误.

让AI代理来处理繁琐的部分

如果您使用ClaudeCode、Cursor或类似的代理，打开 Capgo技能 包括 capacitor-app-upgrade-v7-to-v8 和 capacitor-app-upgrades 用于多个重大版本跳转。使用 bunx skills add Cap-go/capgo-skills 并要求代理升级应用程序。它运行迁移工具，然后检查CLI通常会忽略的步骤，例如Gradle语法、Kotlin选项和CI图像。

什么是下一步

Capacitor 9 已经进入预发布阶段。一旦您稳定在 8 上，请阅读 准备好 Capacitor 9 所以下一次升级会更小。