跳到主要内容
版本：v8

从 Capacitor 7 升级到 Capacitor 8

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

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

iOS 上的 appendUserAgent 曾存在一个错误，即在追加用户代理前会添加两个空格，该问题现已修复。如果你想防止用户代理发生变化，请在 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 的 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 相关的更新。首先，运行 工具 -> AGP 升级助手，并在下拉菜单中选择 8.13.0 作为要更新的版本。然后点击 运行选定步骤。

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，请在 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> 内添加 <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。### 地理位置

  • kotlinxCoroutinesVersion 变量已更新至 1.10.2。

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

Google 地图​

  • 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。

推送通知​

  • firebaseMessagingVersion 变量已更新至 25.0.1。

屏幕方向​

在 Android 16 及更高版本上，lock 方法对大屏幕设备（例如平板电脑）无效。您可以通过在 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

启动画面​

  • coreSplashScreenVersion 变量已更新至 1.2.0。

状态栏​

移除了会发送 .capacitorViewDidAppear 和 .capacitorViewWillTransition 事件的 CAPNotifications.swift 和 CAPBridgeViewController.swift 文件。 您可以通过 @capacitor/ios 监听这些事件。

Contents

编辑此页