跳到主要内容
版本：v8

从 Capacitor 6 更新到 Capacitor 7

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

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

bundledWebRuntime 配置选项已被删除。如果您将其设置为 false，则可以安全地删除它。如果您将其设置为 true，则必须使用 bundler 在您的应用中捆绑 @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 Upgrade Assistant

更新 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"

Plugins​

插件已更新到版本 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

编辑此页