跳到主要内容
版本：v8

从 Capacitor 7 更新到 Capacitor 8

在本指南中，您将找到将项目更新到当前 Capacitor 8 版本的步骤，以及我们官方插件的破坏性更改列表。

Capacitor 配置文件中的破坏性更改​

appendUserAgent 在 iOS 上有一个错误，在附加用户代理之前附加了两个空格，并且已被修复。如果您想阻止用户代理更改，请在 ios.appendUserAgent 上添加一个额外的空格。不要在根 appendUserAgent 上这样做，因为它也会在 Android 上添加空格。

android.adjustMarginsForEdgeToEdge 已被删除，取而代之的是我们新的 System Bars 核心插件，它将处理现代 Android 中的边到边问题。

简而言之，边距处理已被删除，转而使用 env / CSS 变量来处理边到边。阅读此处以获取更多信息和有关如何在应用中实施的详细信息。

@capacitor/cli 中的破坏性更改​

Capacitor CLI 现在默认创建 iOS SPM 项目。 虽然它不影响现有应用，但如果您删除 ios 文件夹并再次运行 npx cap add ios，它将使用 SPM 模板创建，如果要使用 CocoaPods 模板，请运行 npx cap add ios --packagemanager CocoaPods。

@capacitor/android 中的破坏性更改​

bridge_layout_main.xml 文件已被删除，如果您在应用代码或插件代码中引用它，请改用 capacitor_bridge_layout_main.xml。

@capacitor/ios 中的破坏性更改​

Capacitor 现在为 viewDidAppear 和 viewWillTransition 发出 CAPBridgeViewController 的通知，如果您使用 CAPBridgeViewController 扩展来发出这些事件，您应该删除它们。

NodeJS 22+​

Capacitor 8 需要 NodeJS 22 或更高版本。（建议使用最新的 LTS 版本。）

使用 CLI 迁移​

将 Capacitor CLI 的 latest 版本安装到您的项目中：

npm i -D @capacitor/cli@latest

安装完成后，只需运行以下命令即可让 CLI 为您处理迁移。

npx cap migrate

如果迁移的任何步骤无法完成，终端输出中会提供其他信息。手动迁移的步骤在下面列出。

iOS​

以下指南介绍了如何将 Capacitor 7 iOS 项目升级到 Capacitor 8。

升级 Xcode​

Capacitor 8 需要 Xcode 26.0+。

提高 iOS 部署目标​

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

然后，如果项目使用 CocoaPods，请打开 ios/App/Podfile 并将 iOS 版本更新到 15.0：

platform :ios, '15.0'

Android​

以下指南介绍了如何将 Capacitor 7 Android 项目升级到 Capacitor 8。

升级 Android Studio​

Capacitor 8 需要 Android Studio Otter | 2025.2.1 或更新版本。

更新完成后，Android Studio 可以帮助您处理一些与 gradle 相关的更新。要开始，请运行 Tools -> AGP Upgrade Assistant 并在下拉列表中选择 8.13.0 作为要更新的版本。然后单击 Run selected steps。

APG Upgrade Assistant

更新 Android 项目变量​

在您的 variables.gradle 文件中，将值更新为以下新的最小值

minSdkVersion = 24
compileSdkVersion = 36
targetSdkVersion = 36
androidxActivityVersion = '1.11.0'
androidxAppCompatVersion = '1.7.1'
androidxCoordinatorLayoutVersion = '1.3.0'
androidxCoreVersion = '1.17.0'
androidxFragmentVersion = '1.8.9'
coreSplashScreenVersion = '1.2.0'
androidxWebkitVersion = '1.14.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.3.0'
androidxEspressoCoreVersion = '3.7.0'
cordovaAndroidVersion = '14.0.1'

替换已弃用的 Gradle 属性名称语法​

Gradle 已弃用属性名称语法，现在建议在值之前使用 =。虽然目前只会导致警告，但在将来会中断。

# app/build.gradle
android {
-    namespace "com.getcapacitor.myapp"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.getcapacitor.myapp"
+    compileSdk = rootProject.ext.compileSdkVersion
...
     defaultConfig {
...
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'

更新 google services 插件​

# build.gradle

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

更新 gradle 插件到 8.13.0​

# build.gradle

    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

更新 kotlin 版本​

如果您的项目使用 kotlin，请将 kotlin_version 变量更新到 '2.2.20'。

将 density 添加到 configChanges​

为了防止 webView 在应用调整大小时重新加载，请将 density 添加到 AndroidManifest.xml 中应用 activity 的 configChanges。

- android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation"
+ android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

Plugins​

插件已更新到版本 8.0.0，请确保更新它们以使用最新版本。

以下插件功能已被修改或删除。相应地更新您的代码。

Action Sheet​

  • androidxMaterialVersion 变量已更新到 1.13.0。

Barcode Scanner​

scanOrientation 选项在 Android 16 及更高版本的大屏幕（例如平板电脑）上不起作用。您可以通过向 AndroidManifest.xml 中的 <application> 或 <activity> 内添加 <property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /> 来选择退出此行为。但请记住，此选择退出是暂时的，在 Android 17 上将不再起作用。Android 不建议为大屏幕设置特定方向。常规 Android 手机不受此更改的影响。有关更多信息，请查看 https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts 上的 Android 文档

Browser​

  • androidxBrowserVersion 变量已更新到 1.9.0。

Camera​

  • androidxExifInterfaceVersion 变量已更新到 1.4.1。
  • androidxMaterialVersion 变量已更新到 1.13.0。

Geolocation​

  • kotlinxCoroutinesVersion 变量已更新到 1.10.2。
  • timeout 属性现在应用于 Android 和 iOS 上的所有请求，而不仅仅是 Web 和 Android 上的 getCurrentPosition。这与插件中的文档一致。如果您开始在使用 watchPosition 时遇到超时，请考虑使用更高的 timeout 值。对于 Android 上的 watchPosition，您可以使用 8.0.0 版本中引入的 interval 参数。

Google Maps​

  • googleMapsPlayServicesVersion 变量已更新到 19.2.0。
  • googleMapsUtilsVersion 变量已更新到 3.19.1。
  • googleMapsKtxVersion 变量已更新到 5.2.1。
  • googleMapsUtilsKtxVersion 变量已更新到 5.2.1。
  • kotlinxCoroutinesVersion 变量已更新到 1.10.2。
  • androidxCoreKTXVersion 变量已更新到 1.17.0。
  • kotlin_version 变量已更新到 2.2.20。

Push Notifications​

  • firebaseMessagingVersion 变量已更新到 25.0.1。

Screen Orientation​

lock 方法在 Android 16 及更高版本的大屏幕（例如平板电脑）上不起作用。您可以通过向 AndroidManifest.xml 中的 <application> 或 <activity> 内添加 <property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /> 来选择退出此行为。但请记住，此选择退出是暂时的，在 Android 17 上将不再起作用。Android 不建议为大屏幕设置特定方向。常规 Android 手机不受此更改的影响。有关更多信息，请查看 https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts 上的 Android 文档

Splash Screen​

  • coreSplashScreenVersion 变量已更新到 1.2.0。

Status Bar​

删除了发出 .capacitorViewDidAppear 和 .capacitorViewWillTransition 事件的 CAPNotifications.swift 和 CAPBridgeViewController.swift。 您可以从 @capacitor/ios 监听它们。

Contents

编辑此页