跳到主要内容
版本：v5

从 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：

npm i -D @capacitor/cli@latest

安装完成后，只需运行以下命令即可让 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 相关更新和构建文件的包迁移。首先运行 工具 -> 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​

如果所有插件都已使用 AndroidX 库而非旧版 Android 支持库，可移除此行：

# 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 中，https 将成为 现有应用 的 androidScheme 默认值，以便更好地支持 自动填充凭证 功能。

更改 scheme 等同于应用运行在不同域名下，可能导致 cookies、localstorage 等存储的数据无法访问。为避免数据丢失，建议现在就将 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+ 系统中，除非添加 entitlements，否则 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

编辑此页