跳到主要内容
版本：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：

npm i -D @capacitor/cli@latest

安装完成后，执行以下命令让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相关更新及构建文件中的包迁移。首先运行工具 -> AGP升级助手。

AGP升级助手

更新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服务插件​

# 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-82.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中的appactivity内为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

编辑此页