跳到主要内容
版本：v8

从 Capacitor 7 更新到 Capacitor 8

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

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

appendUserAgent 在 iOS 上曾存在一个错误，即在附加用户代理前会附加两个空格，此问题已修复。如果您想防止用户代理被更改，请在 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 现在会发出 CAPBridgeViewController 的 viewDidAppear 和 viewWillTransition 通知。如果您使用 CAPBridgeViewController 扩展来发出这些事件，则应将其移除。

NodeJS 22+​

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

使用 CLI 进行迁移​

将 Capacitor CLI 的 latest 版本安装到您的项目中：

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。

APG 升级助手

更新 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'。

向 configChanges 添加 density​

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

- 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> 标签内添加 <property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /> 来选择退出此行为。但请注意，此选择退出是临时的，并且对 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> 标签内添加 <property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /> 来选择退出此行为。但请注意，此选择退出是临时的，并且对 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

编辑此页