跳到主要内容
版本：v6

从 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 版本安装到项目中：

npm i -D @capacitor/cli@latest

安装完成后，只需运行以下命令让 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 相关的更新及将包移动到构建文件中。首先运行 Tools -> AGP Upgrade Assistant。

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

# 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 中，现有应用的 androidScheme 默认设置为 https，以便更好地支持 Capacitor 应用使用系统自动填充功能。

更改此设置相当于将应用部署到不同域名，意味着存储在 cookies、本地存储等处的数据将无法访问。为避免因此变更导致数据丢失，如果尚未在 Capacitor 配置文件中将 androidScheme 设为 https，应将其设为 http。

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

如果已明确设置为 https，现在可安全移除该配置项。

更新 Kotlin 版本​

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

插件变更​

以下插件功能已修改或移除，请相应调整代码。

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

Action Sheet​

  • androidxMaterialVersion 变量已更新为 1.10.0

Camera​

  • 版本 6 的 Camera 插件现使用 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

编辑此页