从 Capacitor 3 升级到 Capacitor 4

相较于之前的版本升级，Capacitor 3 到 4 的破坏性变更较少。本指南将提供升级项目至 Capacitor 4 当前版本的步骤，并列出官方插件的破坏性变更列表。

使用 CLI 进行迁移

通过 npm i -D @capacitor/cli@latest-4 安装最新版 Capacitor CLI 到项目中。安装完成后，运行 npx cap migrate 命令即可让 CLI 自动处理迁移工作。若某些迁移步骤无法自动完成，终端输出中会提供额外信息。以下是手动迁移的具体步骤。

iOS 升级指南

本部分介绍如何将 Capacitor 3 iOS 项目升级至 Capacitor 4。

提升 iOS 部署目标版本

在 Xcode 项目中执行以下操作：在项目编辑器中选择 Project，打开 Build Settings 标签页。在 Deployment 部分将 iOS Deployment Target 修改为 iOS 13.0。对所有的应用 Targets 重复相同操作。

接着打开 ios/App/Podfile 文件：

1. 在第一行添加：

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

2. 将 iOS 版本更新至 13.0：

platform :ios, '13.0'

3. 在文件末尾添加：

post_install do |installer|
  assertDeploymentTarget(installer)
end

移除废弃代码

从 AppDelegate.swift 中移除不再需要的 touchesBegan 方法：

-override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
-  super.touchesBegan(touches, with: event)
-
-  let statusBarRect = UIApplication.shared.statusBarFrame
-  guard let touchPoint = event?.allTouches?.first?.location(in: self.window) else { return }
-
-  if statusBarRect.contains(touchPoint) {
-      NotificationCenter.default.post(name: .capacitorStatusBarTapped, object: nil)
-  }
-}

可选：移除 Info.plist 中的 NSAppTransportSecurity 条目

NSAppTransportSecurity 仅用于实时重载功能。若未使用实时重载或使用 Ionic CLI 实现该功能，可移除此项配置：

-<key>NSAppTransportSecurity</key>
-<dict>
-		  <key>NSAllowsArbitraryLoads</key>
-  		<true/>
-</dict>

Android 升级指南

本部分介绍如何将 Capacitor 3 Android 项目升级至 Capacitor 4。

更新 Android 项目变量

在 variables.gradle 文件中更新以下最低版本要求，并新增 coreSplashScreenVersion 和 androidxWebkitVersion：

minSdkVersion = 22
compileSdkVersion = 32
targetSdkVersion = 32
androidxActivityVersion = '1.4.0'
androidxAppCompatVersion = '1.4.2'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.8.0'
androidxFragmentVersion = '1.4.1'
coreSplashScreenVersion = '1.0.0-rc01'
androidxWebkitVersion = '1.4.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.1.3'
androidxEspressoCoreVersion = '3.4.0'
cordovaAndroidVersion = '10.1.1'

在 Android Manifest 中添加导出标记

在 AndroidManifest.xml 文件的 <activity> 标签中添加：

android:exported="true"

此标记确保可以打开应用中的"活动"（Activity）。更多信息请参阅 Android 活动元素文档。

信息

默认情况下，AndroidManifest.xml 位于 android/app/src/main/AndroidManifest.xml。

更新 Gradle Google Services 插件

在 android/build.gradle 中将 classpath 'com.google.gms:google-services:4.3.5' 更新为 classpath 'com.google.gms:google-services:4.3.13'。

升级至 Gradle 7

在 File > Project Structure > Project 中调整 Gradle 项目设置。Android Gradle 插件版本应不低于 7.2.1，Gradle 版本应不低于 7.4.2。应用更改后，点击 Android Studio 右上角的大象图标执行 Gradle 同步。

信息

Android Studio 可能提供自动升级至 Gradle 7 的选项。接受建议升级即可！升级方式：打开 build.gradle 文件，点击 💡 图标选择 "Upgrade Gradle"。迁移完成后按上述步骤执行 Gradle 同步。

也可使用 Android Gradle 插件升级助手 完成迁移。

确保使用 Java 11

Capacitor 3 兼容 Java 8 和 11，而 Capacitor 4 仅支持 Java 11。在 Android Studio 中修改：

Preferences > Build, Execution, Deployment > Build Tools > Gradle

将 "Gradle JDK" 修改为 Java 11。

信息

最新版 Android Studio 自带 Java 11，无需额外下载！

启用 Android 插件自动加载

这是 Capacitor 3 中的可选功能，在 Capacitor 4 中变为强制要求（init 方法已被移除）。MainActivity.java 中的 onCreate 方法可以移除。现在通过 npm 安装或移除插件时无需再编辑此文件。

 public class MainActivity extends BridgeActivity {
-    @Override
-    public void onCreate(Bundle savedInstanceState) {
-        super.onCreate(savedInstanceState);
-
-        // Initializes the Bridge
-        this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
-            // Additional plugins you've installed go here
-            add(Plugin1.class);
-            add(Plugin2.class);
-        }});
-    }
 }

调整插件注册顺序

若应用包含自定义插件，需在 super.onCreate 前注册：

 public class MainActivity extends BridgeActivity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
+        registerPlugin(PluginInMyApp.class);
         super.onCreate(savedInstanceState);
-        registerPlugin(PluginInMyApp.class);
     }
 }

可选：使用 Android 12 启动屏新 API

启用推荐的 Android 12 启动屏 API：

• 在 android/app/src/main/res/values/styles.xml 中，将 AppTheme.NoActionBarLaunch 主题的 parent 属性从 AppTheme.NoActionBar 改为 Theme.SplashScreen 并添加所需选项：

<style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
    <item name="android:background">@drawable/splash</item>
</style>

不启用新 API 会导致 Android 12+ 设备出现双重启动屏，旧设备仍使用传统启动屏。

此变更为可选但建议执行，否则修改后 Android Studio 会显示 Cannot resolve symbol 'Theme.SplashScreen' 提示。

• 在 android/app/build.gradle 的依赖项中添加 implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"。

可选：使用 DayNight 主题

要实现根据系统主题自动切换深浅模式，将 android/app/src/main/res/values/styles.xml 中的 <style name="AppTheme.NoActionBar" parent="Theme.AppCompat.NoActionBar"> 改为 <style name="AppTheme.NoActionBar" parent="Theme.AppCompat.DayNight.NoActionBar">。

可选：从 Gradle 文件中移除 jcenter()

由于 Cordova 兼容层现已托管在 Maven Central，可移除 jcenter()。若使用其他插件或原生依赖，请确认它们不依赖 Jcenter 后再移除。

插件变更

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

存储插件

@capacitor/storage 插件更名为 @capacitor/preferences 以更准确反映用途，API 保持不变。

相机插件

• 移除 preserveAspectRatio 设置
• 不再提示缺失 iOS 使用描述
• androidxMaterialVersion 更新至 1.6.1
• androidxExifInterfaceVersion 更新至 1.3.3

操作表插件

• ShowActionsOptions.title 变为可选
• androidxMaterialVersion 更新至 1.6.1

iOS 专属变更

• buildActionSheet 的标题和消息变为可选

推送通知插件

• 为 registrationError 事件新增 RegistrationError 类型
• importance 变为可选，默认值 3
• deleteChannel 现仅接收频道 ID 而非完整对象
• firebaseMessagingVersion 更新至 23.0.5
• Android 现遵循 presentationOptions 配置选项

本地通知插件

• importance 变为可选，默认值 3
• deleteChannel 现仅接收频道 ID 而非完整对象
• Android 12+ 需要精确通知权限

应用插件

• App.exitApp() 现在返回 Promise

地理定位插件

• getCurrentPosition() 忽略超时设置
• playServicesLocationVersion 更新至 20.0.0
• 应用进入后台时停止位置更新
• 系统定位服务关闭时抛出错误

文件系统插件

• copy 现在返回被复制文件的路径
• ReaddirResult 现在返回包含文件元数据的 FileInfo 对象数组
• StatResult 在各平台返回统一格式

设备插件

• iOS 的 model 现在返回精确型号（如从 "iPhone" 变为 "iPhone13.4"）
• getLanguageCode() 在 Web 端返回简写语言代码（与其他平台一致），获取完整代码请使用 getLanguageTag()

对话框插件

• title 变为可选

键盘插件

• style 配置选项现在使用 KeyboardStyle 枚举

toast 插件

• Android 12 及以上版本所有 toast 显示在底部

浏览器插件

• androidxBrowserVersion 更新至 1.4.0

启动屏插件

• 若启用 Android 12 启动屏新 API，初始启动屏大多配置选项不可用（但 show() 调用的启动屏仍可用）
• Android 12+ 设备上初始启动屏与 show() 显示的启动屏不同