跳到主要内容
版本：v8

在插件中将 Capacitor 升级到 8.0

使用 @capacitor/plugin-migration-v7-to-v8​

在插件文件夹中，运行 npx @capacitor/plugin-migration-v7-to-v8@latest，它将自动执行所有文件更改。

手动更新文件​

更新 Capacitor 依赖​

将 devDependencies 中的 @capacitor/cli、@capacitor/core、@capacitor/android 和 @capacitor/ios 更新为 ^8.0.0。 将 peerDependencies 中的 @capacitor/core 更新为 >=8.0.0。

更新 Android 插件变量​

在你的 build.gradle 文件中，更新以下包版本：

ext {
+   // 注意：以下一些依赖项是可选的 - 只添加/更新你的插件实际使用的依赖项。
+   // 如果你使用了以下任何依赖项，请将它们更新为下方显示的版本。
    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
-   androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+   androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
-   androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+   androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
-   androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+   androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+   androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
+   androidxCoordinatorLayoutVersion = project.hasProperty('androidxCoordinatorLayoutVersion') ? rootProject.ext.androidxCoordinatorLayoutVersion : '1.3.0'
+   androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
+   androidxFragmentVersion = project.hasProperty('androidxFragmentVersion') ? rootProject.ext.androidxFragmentVersion : '1.8.9'
+   firebaseMessagingVersion = project.hasProperty('firebaseMessagingVersion') ? rootProject.ext.firebaseMessagingVersion : '25.0.1'
+   androidxBrowserVersion = project.hasProperty('androidxBrowserVersion') ? rootProject.ext.androidxBrowserVersion : '1.9.0'
+   androidxMaterialVersion = project.hasProperty('androidxMaterialVersion') ? rootProject.ext.androidxMaterialVersion : '1.13.0'
+   androidxExifInterfaceVersion = project.hasProperty('androidxExifInterfaceVersion') ? rootProject.ext.androidxExifInterfaceVersion : '1.4.1'
+   coreSplashScreenVersion = project.hasProperty('coreSplashScreenVersion') ? rootProject.ext.coreSplashScreenVersion : '1.2.0'
+   androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}

更新 targetSDK / compileSDK 到 36 以及 minSDK 到 24​

# build.gradle

android {
-    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
    defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
    ...
    }
}

更新 gradle 插件到 8.13.0​

    dependencies {
-       classpath 'com.android.tools.build:gradle:8.7.2'
+       classpath 'com.android.tools.build:gradle:8.13.0'
    }

更新 gradle wrapper 到 8.14.3​

# gradle-wrapper.properties

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

更新 Gradle 属性赋值语法​

Gradle 8 弃用了属性的空格赋值语法。将所有属性赋值更新为使用 = 运算符。有关更多详细信息，请参阅 Gradle 升级指南。

以下属性通常需要从空格赋值更新为 = 赋值：

# build.gradle

repositories {
    mavenCentral()
    maven {
-        url "https://plugins.gradle.org/m2/"
+        url = "https://plugins.gradle.org/m2/"
    }
}

android {
-    compileSdk 36
+    compileSdk = 36
-    namespace 'com.example.plugin'
+    namespace = 'com.example.plugin'
}

lintOptions {
-    abortOnError false
+    abortOnError = false
}

注意：属性赋值需要使用 = 运算符。方法调用（如 mavenCentral()）保持不变，不使用 = 运算符。

更新到 Java 21（推荐）​

我们建议使用 Java 21 以获得与 Android Gradle Plugin 8.13.0 和 Android SDK 36 的最佳兼容性，不过 Java 17+ 也受支持。

# build.gradle
compileOptions {
-    sourceCompatibility JavaVersion.VERSION_17
+    sourceCompatibility JavaVersion.VERSION_21
-    targetCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_21
}

更新 kotlin_version​

如果你的插件使用 kotlin，请将默认的 kotlin_version 更新为 2.2.20。这是从 Kotlin 1.x 的主版本升级，包含破坏性变更。

# build.gradle
buildscript {
-    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '1.9.25'
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
    repositories {

Kotlin 2.2 破坏性变更​

Kotlin 2.2.0 包含若干来自 Kotlin 1.x 的破坏性变更。以下是需要注意的关键变更：

  • kotlinOptions{} 代码块：Gradle 中的 kotlinOptions{} 代码块已弃用并会引发错误。请将其替换为 compilerOptions{} 代码块（如下所示）。
  • 移除 kotlin-android-extensions 插件：kotlin-android-extensions 插件已被移除。对于 Parcelable 实现，请使用 kotlin-parcelize 插件；对于合成视图，请使用 Android Jetpack 的视图绑定。

有关破坏性变更和迁移指南的完整列表，请参阅 Kotlin 2.2.0 发布说明。

将 kotlinOptions 更新为 compilerOptions​

Kotlin 2.0+ 要求使用新的 compilerOptions API 替代 kotlinOptions。android {} 内部的 kotlinOptions 代码块已弃用。

# build.gradle

+ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
android {
    ...
-    kotlinOptions {
-        jvmTarget = '17'
-    }
}

+ kotlin {
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_21
+    }
+}

注意：如果你使用的是 Java 21（推荐），请使用 JvmTarget.JVM_21，或者根据你的 Java 版本进行匹配。Java 17+ 受支持，但建议使用 Java 21 以获得最佳兼容性。

更新 google services 插件​

# build.gradle

    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
-       classpath 'com.google.gms:google-services:4.4.2'
+       classpath 'com.google.gms:google-services:4.4.4'

提高 iOS 部署目标到 15​

更新插件的 .podspec 文件

-  s.ios.deployment_target = '14.0'
+  s.ios.deployment_target = '15.0'

SPM 兼容的插件​

更新 Package.swift 文件

-    platforms: [.iOS(.v14)],
+    platforms: [.iOS(.v15)],

旧结构的插件​

在 Xcode 项目中执行以下操作：在项目编辑器中选择 Project，然后打开 Build Settings 选项卡。在 Deployment 部分下，将 iOS Deployment Target 更改为 iOS 15.0。对任何应用 Targets 重复相同的步骤。

然后，打开 ios/Podfile 并将 iOS 版本更新为 15.0：

-platform :ios, '14.0'
+platform :ios, '15.0'

更新 Capacitor SPM 依赖​

在 SPM 兼容的插件中，更新 Package.swift 文件以使用版本 8.0.0

    dependencies: [
-        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
    ],

Contents

编辑此页