从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。对所有的app Targets重复相同步骤。
然后，打开ios/App/Podfile并执行以下操作：
- 在第一行添加：
require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'
- 将iOS版本更新至13.0：
platform :ios, '13.0'
- 在最后一行添加：
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中添加android:exported标签
在AndroidManifest.xml文件中，需要在<activity>标签内添加以下行：
android:exported="true"
该标签确保你能打开应用中的这个"Activity"（即界面）。了解更多关于此标签及其他标签的信息，请查阅Android的<activity>参考文档。
默认情况下，你的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'以更新Google Services插件。
升级至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插件升级助手来完成迁移。该工具的操作步骤可在Android文档中找到。
确保使用Java 11
Capacitor 3兼容Java 8和11，但从Capacitor 4开始仅支持Java 11。在Android Studio中按以下路径修改：
Preferences > Build, Execution, Deployment > Build Tools > Gradle
在此处将"Gradle JDK"修改为Java 11。
Java 11已随最新版Android Studio一同发布，无需额外下载！
切换至自动Android插件加载
这在Capacitor 3中是可选变更，但由于init方法已被移除，现在升级Capacitor 4时必须执行。在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>
若不启用Android 12启动画面API，在Android 12+设备上会出现双重启动画面，旧版设备则会使用旧的启动画面。
此变更是可选的，但建议执行以避免Android Studio在执行上述变更后显示Cannot resolve symbol 'Theme.SplashScreen'消息。
- 在
android/app/build.gradle的dependencies部分添加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()
在之前的Capacitor版本中，由于我们的Cordova兼容层托管在Jcenter上，必须使用jcenter()。但现在我们使用了托管在Maven Central的最新版Cordova Android。因此，你可以从build.gradle文件中完全移除jcenter()。如果你使用其他插件或原生依赖，请确保它们不托管在Jcenter上后再移除！
插件
以下插件功能已被修改或移除。请相应更新你的代码。
存储
@capacitor/storage插件已更名为@capacitor/preferences以更准确地反映其用途。API保持不变。
相机
- 移除了
preserveAspectRatio设置 - 插件不再提示iOS使用描述缺失
androidxMaterialVersion变量更新为1.6.1androidxExifInterfaceVersion变量更新为1.3.3
动作表单
ShowActionsOptions.title现在变为可选androidxMaterialVersion变量更新为1.6.1
仅iOS
buildActionSheet的标题和消息现在变为可选
推送通知
- 为
registrationError事件新增RegistrationError类型 importance现在变为可选，默认为3deleteChannel现在仅接收频道ID而非整个对象firebaseMessagingVersion变量更新为23.0.5- Android现在会遵守
presentationOptions配置选项
本地通知
importance现在变为可选，默认为3deleteChannel现在仅接收频道ID而非整个对象- Android 12+需要特定权限来实现精确通知
应用
App.exitApp()现在返回一个Promise
地理位置
getCurrentPosition()现在忽略超时设置playServicesLocationVersion更新为20.0.0- 当应用进入后台状态时，插件会停止位置更新
- 如果系统定位服务被禁用，插件现在会抛出错误
文件系统
copy现在返回被复制文件的路径ReaddirResult现在返回FileInfo对象数组，其中包含每个文件的URI及相关元数据StatResult已统一，在所有平台上返回相同内容
设备
model在iOS上现在返回精确型号（从"iPhone"变为"iPhone13.4"）getLanguageCode()在web端现在返回短语言代码（与其他平台一致），要获取完整代码请使用getLanguageTag()
对话框
title现在变为可选
键盘
style配置选项现在使用KeyboardStyle枚举作为选项
提示
- 在Android 12及更新版本上，所有提示都显示在底部
浏览器
androidxBrowserVersion变量更新为1.4.0
启动画面
- 如果切换到新的Android 12启动画面API，大多数配置选项将不适用于初始启动画面，但调用
show()时显示的启动画面仍可用这些选项。此外，在Android 12+设备上，初始启动画面与通过show()方法显示的启动画面不同。