跳到主要内容
版本：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 的 latest 版本安装到您的项目中：

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。Java 17 随 Android Studio Flamingo 一起提供。无需额外下载！

更新后，Android Studio 可以协助完成一些与 gradle 相关以及将包移到构建文件中的更新。首先运行 Tools -> AGP Upgrade Assistant。

AGP 升级助手

更新 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 Services​

# 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 operating system, and which are packaged with your app's APK
# https://developer.android.com/topic/libraries/support-library/androidx-rn
android.useAndroidX=true
- # Automatically convert third-party libraries to use AndroidX
- android.enableJetifier=true

将 package 移到 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 的默认设置，以使 Capacitor 应用能够更好地使用系统的 自动填充功能。

更改 scheme 相当于在不同的域名上发布您的应用程序，这意味着存储在 cookie、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

编辑此页