跳到主要内容
版本：v6

从Capacitor 4升级至Capacitor 5

相较于之前的版本升级，Capacitor 4到5的破坏性变更非常少。本指南将提供升级至当前Capacitor 5版本的步骤，以及官方插件的破坏性变更列表。

NodeJS 16+ 要求​

Node 12已终止支持，Node 14也将在2023年4月30日终止支持。Capacitor 5要求NodeJS 16或更高版本（推荐使用最新的LTS版本）。

使用CLI进行迁移​

在项目中安装Capacitor CLI的latest-5版本：

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

安装完成后，只需运行以下命令让CLI自动处理迁移：

npx cap migrate

如果迁移过程中有任何步骤无法完成，终端输出中会提供额外信息。以下是手动迁移的具体步骤。

使用VS Code扩展进行迁移​

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

iOS平台升级指南​

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

升级Xcode​

Capacitor 5要求Xcode 14.1或更高版本。

更新.gitignore文件​

修改.gitignore文件如下：

- App/Podfile.lock
+ App/output

使用单一应用图标​

Xcode 14支持1024x1024的单一应用图标，因此可以清理AppIcon.appiconset中所有不必要的尺寸。

使用单一尺寸应用图标

Android平台升级指南​

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

升级Android Studio​

Capacitor 5要求Android Studio Flamingo | 2022.2.1或更新版本，因为使用了需要Java JDK 17的Gradle 8。Android Studio Flamingo已内置Java 17，无需额外下载！

更新后，Android Studio可协助处理与gradle相关的更新及将包迁移至build文件。首先运行工具 -> AGP升级助手。

APG升级助手

更新Android项目变量​

在variables.gradle文件中更新以下最低版本值：

minSdkVersion = 22
compileSdkVersion = 33
targetSdkVersion = 33
androidxActivityVersion = '1.7.0'
androidxAppCompatVersion = '1.6.1'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.10.0'
androidxFragmentVersion = '1.5.6'
coreSplashScreenVersion = '1.0.0'
androidxWebkitVersion = '1.6.1'
junitVersion = '4.13.2'
androidxJunitVersion = '1.1.5'
androidxEspressoCoreVersion = '3.5.1'
cordovaAndroidVersion = '10.1.1'

更新Google服务​

# build.gradle

    dependencies {
-       classpath 'com.google.gms:google-services:4.3.13'
+       classpath 'com.google.gms:google-services:4.3.15'

更新gradle插件至8.0.0​

# build.gradle

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

更新gradle wrapper至8.0.2​

# gradle-wrapper.properties

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

禁用Jetifier​

如果没有使用仍依赖旧版android支持库（而非AndroidX等效库）的插件，请移除此行：

# gradle.properties

# Android操作系统，随应用APK打包
# https://developer.android.com/topic/libraries/support-library/androidx-rn
android.useAndroidX=true
- # 自动转换第三方库使用AndroidX
- android.enableJetifier=true

将包声明移至build.gradle​

# AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
- <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-     package="[YOUR_PACKAGE_ID]">
+ <manifest xmlns:android="http://schemas.android.com/apk/res/android">
# build.gradle

android {
+     namespace "[YOUR_PACKAGE_ID]"
      compileSdkVersion rootProject.ext.compileSdkVersion

更新androidScheme​

在Capacitor 6中，为更好支持系统自动填充功能，现有应用的androidScheme默认将改为https。

修改此配置相当于将应用部署到不同域名，意味着存储在cookie、localstorage等中的数据将无法访问。为避免数据丢失，应在Capacitor配置文件中立即设置scheme为http，即使这是当前默认值：

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

更新kotlin版本​

若项目使用kotlin，将kotlin_version变量更新为'1.8.20'。

插件变更​

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

Action Sheet插件​

  • androidxMaterialVersion变量已更新至1.8.0

Browser插件​

  • androidxBrowserVersion变量已更新至1.5.0

Camera插件​

  • Android 13要求在AndroidManifest.xml中声明读取媒体图片权限(<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>)
  • androidxMaterialVersion变量已更新至1.8.0
  • androidxExifInterfaceVersion变量已更新至1.3.6

Device插件​

  • DeviceId.uuid更名为DeviceId.identifier
  • iOS 16+上，除非添加相应的权限声明，否则DeviceInfo.name将返回通用设备名称

Geolocation插件​

  • playServicesLocationVersion已更新至21.0.1

Google Maps插件​

  • 多个版本变量更新：
    • googleMapsPlayServicesVersion → 18.1.0
    • googleMapsUtilsVersion → 3.4.0
    • googleMapsKtxVersion → 3.4.0
    • googleMapsUtilsKtxVersion → 3.4.0
    • kotlinxCoroutinesVersion → 1.6.4
    • androidxCoreKTXVersion → 1.10.0
    • kotlin_version → 1.8.20

Local Notifications插件​

  • Android 13需要新的运行时权限检查才能调度本地通知，当目标SDK为33时，需相应调用checkPermissions()和requestPermissions()

Push Notifications插件​

  • Android 13需要新的运行时权限检查才能接收推送通知，当目标SDK为33时，需相应调用checkPermissions()和requestPermissions()
  • firebaseMessagingVersion变量已更新至23.1.2

Status Bar插件​

  • iOS上，状态栏默认动画效果更改为FADE

Contents

编辑此页