当前位置：首页 > news >正文

鸿蒙HarmonyOS NEXT设备升级应用数据迁移流程

news 来源：原创 2025/7/5 10:39:15

数据迁移是什么

什么是数据迁移，对用户来讲就是本地数据的迁移，终端设备从HarmonyOS 3.1 Release API 9及之前版本（单框架）迁移到HarmonyOS NEXT（双框架）后保证本地数据不丢失。例如，我在某APP上面是登录状态，从单框架升级到双框架打开APP后依旧是登录状态，这就是数据迁移，并不是云端数据的处理，是本地数据的处理。当然，这只是其中一个用户信息，除用户信息外还有一系列开发者用到的设备数据等等，需要迁移。

HarmonyOS NEXT提供了“数据迁移框架”和“备份恢复框架”，为开发者提供应用数据的迁移和转换能力。开发者完成适配，APK应用切换为HarmonyOS应用后，可继承原APK应用中适配HarmonyOS应用的数据。流程大概如下：

数据迁移机制

应用数据迁移任务需要执行的步骤包括：应用安装，数据迁移和数据恢复。

应用安装步骤：
1. “数据迁移框架”向华为应用市场发送HarmonyOS应用下载和安装请求。
2. 华为应用市场下载并安装HarmonyOS应用。
数据迁移步骤：

在HarmonyOS应用安装完成之后，“数据迁移框架”将应用沙箱数据从中间目录搬迁到备份恢复目录。

数据恢复步骤：
1. 在应用数据搬迁到备份恢复目录后，“数据迁移框架”向“备份恢复框架”发送应用数据恢复请求。
2. “备份恢复框架”拉起应用的“BackupExtensionAbility”独立进程，启动应用数据恢复。
3. 应用通过“BackupExtensionAbility”从备份恢复目录加载APK应用的数据，处理后保存到HarmonyOS应用沙箱中，完成应用数据恢复。
4. “备份恢复框架”在应用数据恢复完成后，清空备份恢复目录。

应用适配流程

迁移目录对应关系

开发者需要在HarmonyOS应用的代码中，实现“BackupExtensionAbility”，使应用接入到“备份恢复框架”中，完成应用数据的转换和迁移。后续HarmonyOS应用通过访问HarmonyOS应用沙箱获取应用的数据。

![](https://i-blog.csdnimg.cn/img_convert/f18cdc25050d268879b3465d0cb3d433.png =600x300)

备份恢复目录如下表中所示：

代码实现

创建BackupExtensionAbility，APP在BackupExtensionAbility中实现应用的数据转换和迁移逻辑。

import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';const TAG = `BackupExtensionAbility`;/*** serviceExt进程入口*/
export default class BackupExtension extends  BackupExtensionAbility {onBackup () {console.log(TAG,`onBackup ok`);}/*** 数据恢复处理接口。接口是同步接口，其内部所有的异步操作请进行同步等待。** @param bundleVersion 版本信息*/async onRestore (bundleVersion : BundleVersion): Promise<void> {console.log(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);//bundleVersion.name的前缀为“0.0.0.0”时，表示终端设备从HarmonyOS升级到HarmonyOS NEXT数据迁移场景if (bundleVersion.name.startsWith("0.0.0.0")){// 在此处实现终端设备从HarmonyOS 4.x升级到HarmonyOS NEXT后，应用数据的转换和迁移// 涉及异步操作请进行同步等待console.log(TAG, `HarmonyOS to HarmonyOS NEXT scenario`);} else {// 在此处实现从HarmonyOS NEXT设备迁移到HarmonyOS NEXT设备后，应用数据的处理。无特殊要求，可以空实现// 涉及异步操作请进行同步等待console.log(TAG, `Other scenario`);}}
}

module.json5中配置

"extensionAbilities": [{"description": "DemoBackupExtension","icon": "$media:app_icon","name": "BackupExtensionAbility","srcEntry": "./ets/backupExtension/BackupExtension.ets",  // 对应BackupExtension.ets在代码仓中的位置"type": "backup",                                         // 类型需要选择backup"exported": false,"metadata": [                                             // 对应注册的元数据资源{"name": "ohos.extension.backup","resource": "$profile:backup_config"}]}
]

数据迁移结果验证

开发者验证

1、将单架构要迁移数据的APP数据通过Android Studio 按下面对应目录导出zip包，然后放到手机本地，或者登录华为账号放到我的云盘里面方便登录下载。

2、下载手动迁移工具 **MigrateTool ，**选择刚才导出的zip文件，再输入要迁入到的应用签名，点击启动迁移，迁移提示成功之后（注意如果迁移失败，可能是zip数据问题，根据上面目录排查）。打开APP验证即可功能。

)

QA端到端验证

如果是已经上架的应用，可以发布一个内测版本，然后审核通过后指定设备做线上验证。

当前开发者持有的终端设备为HarmonyOS NEXT。开发者在验证升级前，需要将设备从HarmonyOS NEXT回退到HarmonyOS。在应用适配完成并上架到华为应用市场之后，开发者需要联系华为方技术支撑人员提供版本，支持开发者将终端设备从HarmonyOS NEXT回退到HarmonyOS。系统回退的入口为：设置 > 通用 > 开发者模式 > 系统回退。
将终端设备回退到HarmonyOS后，需要预置APK应用的数据。在数据预置完成后，开发者需要联系华为方技术支撑人员提供版本，支持开发者将终端设备从HarmonyOS升级到HarmonyOS NEXT。系统更新的入口为：设置 > 系统和更新 > 软件更新。
终端设备成功从HarmonyOS升级到HarmonyOS NEXT，走过开机向导界面后，开始执行应用数据迁移。开发者请在应用数据迁移结束后，验证应该数据迁移的结果。