跳到主要内容
版本：v7

从 Capacitor 6 升级到 Capacitor 7

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

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

bundledWebRuntime 配置选项已被移除。如果您之前将其设置为 false，可以安全地删除它。如果您之前将其设置为 true，则需要使用打包工具将 @capacitor/core 代码打包到您的应用中。

cordova.staticPlugins 配置选项已被移除。如果您仍有一些 Cordova 插件需要静态链接，应将其更新为使用带有 use-framework 属性的 podspec 标签，而不是使用 framework 标签，因为这在 cordova-ios 7+ 中不再支持。

NodeJS 20+​

Node 18 已于 2023 年 10 月 18 日结束活跃支持。Capacitor 7 需要 NodeJS 20 或更高版本。（推荐使用最新的 LTS 版本。）

遥测功能现在默认启用​

这只影响新用户，因为如果您之前使用过任何 Capacitor 命令，它已经保存了偏好设置。此外，遥测功能在非交互式环境（如 CI 服务器）中不会运行，确保在这些场景中不会收集数据。 您可以使用 npx cap telemetry off 禁用它。

使用 CLI 进行迁移​

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

npm i -D @capacitor/cli@latest-7

安装完成后，只需运行以下命令即可让 CLI 为您处理迁移。

npx cap migrate

如果迁移的任何步骤无法完成，终端输出中将提供更多信息。手动进行迁移的步骤将在下面列出。

iOS​

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

升级 Xcode​

Capacitor 7 需要 Xcode 16.0+。

提高 iOS 部署目标​

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

然后，打开 ios/App/Podfile 并将 iOS 版本更新为 14.0：

platform :ios, '14.0'

Android​

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

升级 Android Studio​

Capacitor 7 需要 Android Studio Ladybug | 2024.2.1 或更高版本以及 Java JDK 21。Java 21 随 Android Studio Ladybug 一起提供。无需额外下载！

更新完成后，Android Studio 可以帮助处理一些与 gradle 相关的更新以及将包移动到构建文件中。首先，运行 Tools -> AGP Upgrade Assistant。

APG 升级助手

更新 Android 项目变量​

在您的 variables.gradle 文件中，将您的值更新为以下新的最低要求：

minSdkVersion = 23
compileSdkVersion = 35
targetSdkVersion = 35
androidxActivityVersion = '1.9.2'
androidxAppCompatVersion = '1.7.0'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.15.0'
androidxFragmentVersion = '1.8.4'
coreSplashScreenVersion = '1.0.1'
androidxWebkitVersion = '1.12.1'
junitVersion = '4.13.2'
androidxJunitVersion = '1.2.1'
androidxEspressoCoreVersion = '3.6.1'
cordovaAndroidVersion = '10.1.1'

更新 google services 插件​

# build.gradle

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

将 gradle 插件更新到 8.7.2​

# build.gradle

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

将 gradle wrapper 更新到 8.11.1​

# gradle-wrapper.properties

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

更新 kotlin 版本​

如果您的项目使用 kotlin，请将 kotlin_version 变量更新为 '1.9.25'。

将 navigation 添加到 configChanges​

这是一个可选更改，用于防止在使用蓝牙键盘时某些设备上的应用重启。 将 navigation 添加到 AndroidManifest.xml 中应用 activity 的 configChanges 中。

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

插件​

插件已更新到版本 7.0.0，请确保将它们更新到最新版本。

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

Action Sheet​

  • androidxMaterialVersion 变量已更新为 1.12.0。

App​

  • 已弃用的类型 AppRestoredResult 已被移除，请使用 RestoredListenerEvent。
  • 已弃用的类型 AppUrlOpen 已被移除，请使用 URLOpenListenerEvent。

Browser​

  • androidxBrowserVersion 变量已更新为 1.8.0。

Camera​

  • androidxExifInterfaceVersion 变量已更新为 1.3.7。
  • androidxMaterialVersion 变量已更新为 1.12.0。

Device​

  • getInfo() 不再返回 diskFree、diskTotal、realDiskFree 和 realDiskTotal，因此可以移除此插件的 PrivacyInfo.xcprivacy 条目。
  • 已弃用的类型 DeviceBatteryInfo 已被移除，请使用 BatteryInfo。
  • 已弃用的类型 DeviceLanguageCodeResult 已被移除，请使用 GetLanguageCodeResult。

Geolocation​

  • playServicesLocationVersion 变量已更新为 21.3.0。

Haptics​

  • 已弃用的类型 HapticsImpactOptions 已被移除，请使用 ImpactOptions。
  • 已弃用的类型 HapticsNotificationOptions 已被移除，请使用 NotificationOptions。
  • 已弃用的类型 HapticsNotificationType 已被移除，请使用 NotificationType。
  • 已弃用的类型 HapticsImpactStyle 已被移除，请使用 ImpactStyle。

Push Notifications​

  • firebaseMessagingVersion 变量已更新为 24.1.0。

Share​

  • androidxCoreVersion 变量已更新为 1.15.0。

Splash Screen​

  • 已弃用的类型 SplashScreenShowOptions 已被移除，请使用 ShowOptions。
  • 已弃用的类型 SplashScreenHideOptions 已被移除，请使用 HideOptions。

Status Bar​

  • setOverlaysWebView() 和 setBackgroundColor() 现在在 iOS 上受支持。
  • androidxCoreVersion 变量已更新为 1.15.0。

Contents

编辑此页