跳到主要内容
版本：v8

从 Capacitor 6 升级到 Capacitor 7

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

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

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

cordova.staticPlugins 配置选项已被移除。如果你仍有某些 Cordova 插件需要设置为静态，应更新为使用包含 use-framework 属性的 podspec 标签，而不是使用 framework 标签，因为 cordova-ios 7+ 不再支持 framework 标签。

NodeJS 20+​

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

遥测现在为选择退出机制​

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

使用 CLI 进行迁移​

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

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 和将 package 移入构建文件相关的更新。首先，运行 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​

这是一个可选更改，用于防止在某些使用蓝牙键盘的设备上应用重启。 请在 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

编辑此页