跳到主要内容
版本：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、本地存储等中的任何数据将不再可访问。为了避免因此更改导致数据丢失，如果您尚未在 Capacitor 配置文件中将 androidScheme 条目设置为 https，则应将其设置为 http。

{
  server: {
    androidScheme: 'http';
  }
}

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

更新 kotlin 版本​

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

插件​

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

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

Action Sheet（操作表）​

  • androidxMaterialVersion 变量已更新至 1.10.0。

Camera（相机）​

  • Capacitor Camera 插件版本 6 现在使用 Photo Picker 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。

Filesystem（文件系统）​

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

Geolocation（地理位置）​

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

Google Maps（谷歌地图）​

  • 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。

Local Notifications（本地通知）​

  • 在 Android 14 上，即使使用了 <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" /> 权限，默认情况下通知也不是精确的，详见此处

Push Notifications（推送通知）​

  • firebaseMessagingVersion 变量已更新至 23.3.1。

Share（分享）​

  • androidxCoreVersion 变量已更新至 1.12.0。

Splash Screen（启动屏）​

  • coreSplashScreenVersion 变量已更新至 1.0.1。

Status Bar（状态栏）​

  • androidxCoreVersion 变量已更新至 1.12.0。

Contents

编辑此页