跳到主要内容
版本：v7

从 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 版本。）

遥测现在默认为 opt-out​

这仅影响新用户，因为如果你之前使用过任何 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 升级助手

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

编辑此页