跳到主要内容
版本：v7

从Capacitor 5升级至Capacitor 6

Capacitor 5到6的破坏性变更被设计得非常少。本指南将提供将项目升级至当前Capacitor 6版本的步骤，以及官方插件的破坏性变更列表。

NodeJS 18+要求​

Node 16已于2023年9月11日终止支持。Capacitor 6要求NodeJS 18或更高版本。（推荐使用最新的LTS版本）

使用CLI进行迁移​

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

npm i -D @capacitor/cli@latest-6

安装完成后，只需运行以下命令即可让CLI为您处理迁移过程。

npx cap migrate

如果迁移步骤中有任何无法完成的情况，终端输出中会提供额外信息。下方列出了手动迁移的步骤。

使用VS Code扩展进行迁移​

如果已安装VS Code扩展，只需查看扩展的推荐部分，即可找到将项目迁移至Capacitor 6的选项。

iOS平台​

以下指南描述如何将Capacitor 5的iOS项目升级至Capacitor 6。

升级Xcode​

Capacitor 6需要Xcode 15.0及以上版本。

SPM支持​

从Cocoapods转换到SPM是一个较大的主题，我们将在另一篇文章中详细说明（即将发布）。

注册自定义插件​

在Capacitor 6中，插件类不再自动注册。对于通过npm安装的插件，CLI会生成插件类列表以编程方式注册它们。但遵循自定义代码指南创建本地插件（不通过npm分发）的用户，需要创建自定义视图控制器并注册插件。

缩放功能​

为与Android行为保持一致，iOS应用默认不再支持缩放。如需启用缩放，请检查zoomEnabled配置选项

Android平台​

以下指南描述如何将Capacitor 5的Android项目升级至Capacitor 6。

升级Android Studio​

由于使用Gradle 8.2，Capacitor 6需要Android Studio Hedgehog | 2023.1.1或更新版本。

升级后，Android Studio可协助完成与gradle相关的更新及将包移至构建文件的操作。首先运行工具 -> AGP升级助手。

APG升级助手

更新Android项目变量​

在variables.gradle文件中，将值更新为以下新最低要求：

minSdkVersion = 22
compileSdkVersion = 34
targetSdkVersion = 34
androidxActivityVersion = '1.8.0'
androidxAppCompatVersion = '1.6.1'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.12.0'
androidxFragmentVersion = '1.6.2'
coreSplashScreenVersion = '1.0.1'
androidxWebkitVersion = '1.9.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.1.5'
androidxEspressoCoreVersion = '3.5.1'
cordovaAndroidVersion = '10.1.1'

更新google services插件​

# build.gradle

    dependencies {
        classpath 'com.android.tools.build:gradle:8.0.0'
-       classpath 'com.google.gms:google-services:4.3.15'
+       classpath 'com.google.gms:google-services:4.4.0'

更新gradle插件至8.2.1​

# build.gradle

    dependencies {
-       classpath 'com.android.tools.build:gradle:8.0.0'
+       classpath 'com.android.tools.build:gradle:8.2.1'

更新gradle wrapper至8.2.1​

# gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
- distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-all.zip
+ distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

更新androidScheme​

在Capacitor 6中，https成为__现有应用__的androidScheme默认设置，以便更好地让Capacitor应用利用系统自动填充功能。

更改方案等同于在另一个域名上发布应用，这意味着存储在cookie、localstorage等中的数据将无法访问。为避免因此变更导致数据丢失，如果您的Capacitor配置文件中没有将androidScheme条目设为https，应将方案设为http。

{
  server: {
    androidScheme: "http"
  }
}

如果已将androidScheme条目设为https，现在可以安全地移除它。

更新kotlin版本​

如果项目使用kotlin，将kotlin_version变量更新为'1.9.10'。

插件​

以下插件功能已修改或移除。请相应更新代码。

对于所有具有监听器的插件，addListener现在只返回一个Promise，如果您在不使用await的情况下将调用结果存储在变量中，代码将无法编译。

操作表​

  • androidxMaterialVersion变量已更新至1.10.0。

相机​

  • Capacitor相机插件v6现在使用照片选择器API，除非使用saveToGallery: true，否则不再需要声明相机权限。如果为false，可以从AndroidManifest.xml中移除以下权限（如果没有其他插件需要它们）：
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  • 在Android上，如果用户取消从图库选择图像，现在返回的错误与其他平台一致，为"User cancelled photos app"。
  • androidxMaterialVersion变量已更新至1.10.0。

文件系统​

  • iOS现在与其他平台一致，将ctime和mtime作为数字而非字符串返回。

地理定位​

  • NSLocationAlwaysUsageDescription (Privacy - Location Always Usage Description) 已弃用，可从Info.plist中移除。
  • playServicesLocationVersion变量已更新至21.1.0。

谷歌地图​

  • iOS原生库已更新，详情请参阅此文档
  • NSLocationAlwaysUsageDescription (Privacy - Location Always Usage Description) 已弃用，可从Info.plist中移除。
  • googleMapsPlayServicesVersion已更新至18.2.0。
  • googleMapsUtilsVersion已更新至3.8.2。
  • googleMapsKtxVersion已更新至5.0.0。
  • googleMapsUtilsKtxVersion已更新至5.0.0。
  • kotlinxCoroutinesVersion已更新至1.7.3。
  • androidxCoreKTXVersion已更新至1.12.0。
  • kotlin_version已更新至1.9.10。

本地通知​

  • 在Android 14上，即使使用了<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />权限，通知默认也不精确，详情请参阅此文档

推送通知​

  • firebaseMessagingVersion变量已更新至23.3.1。

分享​

  • androidxCoreVersion变量已更新至1.12.0。

启动屏​

  • coreSplashScreenVersion变量已更新至1.0.1。

状态栏​

  • androidxCoreVersion变量已更新至1.12.0。

Contents

编辑此页