跳到主要内容
版本：v8

从 Capacitor 7 升级到 Capacitor 8

在本指南中，你将找到将项目更新到当前 Capacitor 8 版本的步骤，以及官方插件的破坏性变更列表。

Capacitor 配置文件中的破坏性变更​

appendUserAgent 在 iOS 上存在一个 bug，会在添加 user agent 之前额外添加两个空格，该问题已修复。如果你希望阻止 user agent 的变化，请在 ios.appendUserAgent 中添加一个额外的空格。不要在根级别的 appendUserAgent 上操作，因为这也会在 Android 上添加空格。

android.adjustMarginsForEdgeToEdge 已被移除，推荐使用我们新的 System Bars 核心插件来处理现代 Android 的边到边问题。

简而言之，边距处理已被移除，推荐使用 env / CSS 变量来处理边到边问题。请阅读此处了解更多信息以及在应用程序中如何实现。

@capacitor/cli 中的破坏性变更​

Capacitor CLI 现在默认创建 iOS SPM 项目。 虽然这不会影响现有应用，但如果你删除 ios 文件夹并重新运行 npx cap add ios，它将使用 SPM 模板创建。如果你希望使用 CocoaPods 模板，请运行 npx cap add ios --packagemanager CocoaPods。

@capacitor/android 中的破坏性变更​

bridge_layout_main.xml 文件已被移除，如果你在应用代码或插件代码中引用了它，请改用 capacitor_bridge_layout_main.xml。

@capacitor/ios 中的破坏性变更​

Capacitor 现在会在 viewDidAppear 和 viewWillTransition 时发出 CAPBridgeViewController 的通知，如果你使用 CAPBridgeViewController 扩展来发出这些事件，应将其移除。

NodeJS 22+​

Capacitor 8 需要 NodeJS 22 或更高版本。（推荐使用最新的 LTS 版本。）

使用 CLI 进行迁移​

将最新版本的 Capacitor CLI 安装到你的项目中：

npm i -D @capacitor/cli@latest

安装完成后，只需运行以下命令，CLI 将为你处理迁移：

npx cap migrate

如果迁移的某些步骤无法完成，终端输出中会提供额外的信息。以下是手动迁移的步骤。

iOS​

以下指南描述了如何将你的 Capacitor 7 iOS 项目升级到 Capacitor 8。

升级 Xcode​

Capacitor 8 需要 Xcode 26.0+。

提升 iOS 部署目标​

在你的 Xcode 项目中执行以下操作：在项目编辑器中选择 Project，然后打开 Build Settings 选项卡。在 Deployment 部分，将 iOS Deployment Target 更改为 iOS 15.0。对所有应用 Targets 重复相同步骤。

然后，如果项目使用的是 CocoaPods，打开 ios/App/Podfile 并将 iOS 版本更新为 15.0：

platform :ios, '15.0'

Android​

以下指南描述了如何将你的 Capacitor 7 Android 项目升级到 Capacitor 8。

升级 Android Studio​

Capacitor 8 需要 Android Studio Otter | 2025.2.1 或更新版本。

更新完成后，Android Studio 可以帮助处理一些与 gradle 相关的更新。首先，运行 Tools -> AGP Upgrade Assistant，然后在下拉菜单中选择 8.13.0 作为要更新的版本。接着点击 Run selected steps。

APG Upgrade Assistant

更新 Android 项目变量​

在你的 variables.gradle 文件中，将值更新为以下新的最低版本：

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'

替换已弃用的 Gradle 属性名语法​

Gradle 已弃用属性名语法，现在推荐在值之前使用 =。目前这只会导致警告，但未来将会导致构建失败。

# app/build.gradle
android {
-    namespace "com.getcapacitor.myapp"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.getcapacitor.myapp"
+    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 Services 插件​

# build.gradle

    dependencies {
        classpath 'com.android.tools.build:gradle:8.7.2'
-       classpath 'com.google.gms:google-services:4.4.2'
+       classpath 'com.google.gms:google-services:4.4.4'

更新 Gradle 插件至 8.13.0​

# build.gradle

    dependencies {
-       classpath 'com.android.tools.build:gradle:8.7.2'
+       classpath 'com.android.tools.build:gradle:8.13.0'

更新 Gradle Wrapper 至 8.14.3​

# gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
- distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
+ distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

更新 Kotlin 版本​

如果你的项目使用了 Kotlin，请将 kotlin_version 变量更新为 '2.2.20'。

添加 density 到 configChanges​

为防止 WebView 在应用调整大小时重新加载，请在 AndroidManifest.xml 的应用 activity 的 configChanges 中添加 density。

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

插件​

插件已更新至 8.0.0 版本，请确保更新它们以使用最新版本。

以下插件功能已被修改或移除。请相应更新你的代码。

Action Sheet​

  • androidxMaterialVersion 变量已更新为 1.13.0。

Barcode Scanner​

scanOrientation 选项在 Android 16 及更高版本的大屏幕设备（如平板电脑）上无效。你可以通过在 AndroidManifest.xml 的 <application> 或 <activity> 中添加 &lt;property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /&gt; 来选择退出此行为。但请注意，此选择退出是临时的，在 Android 17 中将不再起作用。Android 不鼓励为大屏幕设备设置特定方向。普通 Android 手机不受此变更影响。更多信息请查看 Android 文档：https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts

Browser​

  • androidxBrowserVersion 变量已更新为 1.9.0。

Camera​

  • androidxExifInterfaceVersion 变量已更新为 1.4.1。
  • androidxMaterialVersion 变量已更新为 1.13.0。

Geolocation​

  • kotlinxCoroutinesVersion 变量已更新为 1.10.2。
  • timeout 属性现在应用于 Android 和 iOS 上的所有请求，而不仅仅是 Web 和 Android 上的 getCurrentPosition。这与插件文档中的描述一致。如果你在应用中请求位置时开始遇到超时，请考虑使用更高的 timeout 值。对于 Android 上的 watchPosition，你可以使用 8.0.0 版本引入的 interval 参数。

Google Maps​

  • googleMapsPlayServicesVersion 变量已更新为 19.2.0。
  • googleMapsUtilsVersion 变量已更新为 3.19.1。
  • googleMapsKtxVersion 变量已更新为 5.2.1。
  • googleMapsUtilsKtxVersion 变量已更新为 5.2.1。
  • kotlinxCoroutinesVersion 变量已更新为 1.10.2。
  • androidxCoreKTXVersion 变量已更新为 1.17.0。
  • kotlin_version 变量已更新为 2.2.20。

Push Notifications​

  • firebaseMessagingVersion 变量已更新为 25.0.1。

Screen Orientation​

lock 方法在 Android 16 及更高版本的大屏幕设备（如平板电脑）上无效。你可以通过在 AndroidManifest.xml 的 <application> 或 <activity> 中添加 &lt;property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /&gt; 来选择退出此行为。但请注意，此选择退出是临时的，在 Android 17 中将不再起作用。Android 不鼓励为大屏幕设备设置特定方向。普通 Android 手机不受此变更影响。更多信息请查看 Android 文档：https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts

Splash Screen​

  • coreSplashScreenVersion 变量已更新为 1.2.0。

Status Bar​

移除了发出 .capacitorViewDidAppear 和 .capacitorViewWillTransition 事件的 CAPNotifications.swift 和 CAPBridgeViewController.swift 文件。 你可以从 @capacitor/ios 监听这些事件。

Contents

编辑此页