跳到主要内容
版本：v8

从 Capacitor 6 升级到 Capacitor 7

本指南将介绍如何将您的项目升级到当前版本的 Capacitor 7，并列出官方插件的破坏性变更。

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

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

cordova.staticPlugins 配置选项已被移除。如果您仍有需要静态链接的 Cordova 插件，应更新为使用 podspec 标签并添加 use-framework 属性，而不是使用 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。Android Studio Ladybug 自带 Java 21，无需额外下载！

更新完成后，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'。

在 configChanges 中添加 navigation​

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

- 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

编辑此页