DevEco Studio 一体化工程迁移指南

1. 一体化工程迁移

DevEco Studio 从 NEXT Developer Beta1 版本开始，提供开箱即用的开发体验，将 SDK、Node.js、Hvigor、OHPM 等工具链进行合一打包，简化 DevEco Studio 安装配置流程；并提供一体化的历史工程迁移能力，帮助开发者快速完成工程转换。

注意：为了避免数据丢失，迁移前请对工程进行备份。

一体化变更点如下：

变更点	详细说明
删除 compileSdkVersion 字段	删除工程级 build-profile.json5 中的 compileSdkVersion 配置。 说明： - 由于 targetSdkVersion 未配置时值默认与 compileSdkVersion 的值一致，如果之前未配置 targetSdkVersion，targetSdkVersion 的值将与配套的 SDK 版本保持一致；如果之前配置过 targetSdkVersion，targetSdkVersion 的值不变。 - 若工程为 OpenHarmony 工程，则无需执行此步骤。
删除部分 hvigor 文件 & 删除冗余 hvigor 配置	1. 删除 hvigor-wrapper.json。 2. 删除 hvigorw、hvigorw.bat。 3. 删除 hvigor-config.json5 中的 hvigorVersion 字段，并删除 dependencies 中 @ohos/hvigor-ohos-plugin 及 rollup 字段。
删除 HarmonyOS SDK 配置	删除 local.properties 中的 HarmonyOS SDK 配置。若工程为 OpenHarmony 工程，则忽略此步骤。
增加开发态配置	1. 在 hvigor-config.json5 中增加开发态配置版本号 modelVersion。 2. 在工程级的 oh-package.json5 中增加开发态配置版本号 modelVersion。

1.1 自动迁移

1. 打开历史工程，Notifications 通知栏将出现'Sync failed.'同步失败提示，点击 Migrate Assistant，进入迁移助手页面。

说明：可以通过菜单栏 Tools > Migrate Assistant，进入迁移助手页面。

2. 在页面下方的 Migrate Assistant 页签中选择迁移到 5.0.0/5.0.1/5.0.2，并点击 Migrate 按钮，此时将出现弹窗提示开发者进行数据备份。若确认已完成备份，请点击弹窗中 Migrate，启动迁移任务。

3. 待工程重新完成同步，并无其他报错提示，即为迁移成功。

说明：若工程是 NPM 管理的 API 8/9 工程，先按照适配 OHPM 包管理完成升级，再通过菜单栏 Tools > Migrate Assistant，进入迁移助手页面，完成一体化工程自动迁移。

1.2 手动迁移

1.2.1 API 10 及以上历史工程迁移

如自动化迁移不成功或希望进行手动迁移，迁移前同样需对工程进行备份。手动迁移流程如下：

1. 进入工程级 build-profile.json5 文件，删除 compileSdkVersion 配置。若工程为 OpenHarmony 工程，则无需删除 compileSdkVersion 字段。

2. 删除并修改 Hvigor 相关文件：

   • 在左侧工程目录中删除 hvigorw、hvigorw.bat 文件，并删除 hvigor 目录下的 hvigor-wrapper.js 文件。

   

   • 进入 hvigor > hvigor-config.json5 文件中，新增 modelVersion 字段，以 API 12 为例，其值为"5.0.0"。并删除 hvigorVersion 字段、dependencies 中的 @ohos/hvigor-ohos-plugin 和 rollup 字段。

   

3. 在工程级 oh-package.json5 文件中同样也需新增 modelVersion 字段，以 API 12 为例，其值为"5.0.0"。

4. 在 local.properties 文件中，删除 HarmonyOS SDK 配置。若工程为 OpenHarmony 工程，则无需执行此步骤。

5. 点击编辑界面上方 Sync now 或进入菜单栏点击 File > Sync and Refresh Project，重新进行工程同步。若无其他报错，至此历史工程手动迁移完成。

1.2.2 API 9 历史工程迁移

1. 将工程级 build-profile.json5 文件中 compileSdkVersion 字段删除，并将 compatibleSdkVersion 字段从 app 字段下迁移到当前选中的 product 中。当前生效的 product 可以通过点击编辑区域右上方选择。

2. 请将 compatibleSdkVersion 和 targetSdkVersion(若已配置) 从 9 改为 4.0.0(10)，并配置 runtimeOS。版本号需满足 M.S.F(X) 规则的字符串类型，使用英文 . 和 ()。

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "4.0.0(10)",
        "targetSdkVersion": "4.0.0(10)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

3. 将其他各模块级别的 build-profile.json5 文件中 target 字段下配置的 runtimeOS 删除。

4. 剩下的步骤与 API 10 及以上的步骤相同，参考 1.2.1 的步骤二完成余下手动迁移步骤。

说明：

• 一键升级只针对当前选择的 product 生效。
• 如有多个 product，需要分别切换不同 product 后，按照手动升级的方式对工程进行升级。每一个 product 下都需要配置相应的 compatibleSdkVersion 和 runtimeOS。
• 针对 API 8/9 NPM 工程，请先按照适配 OHPM 包管理完成升级，再按照 API 9 历史工程迁移完成手动迁移配置。
• 从 DevEco Studio 4.0 Release 版本开始，代码编辑器及编译构建过程增强了对 ArkTS 语法规范的检查，如果历史工程中存在不符合 ArkTS 语法规范的代码，在迁移完成后可能会报错，需根据具体报错信息修正不符合 ArkTS 语法规范的代码。
• 如果历史工程包含低代码方式开发的界面，在迁移完成后，需要将这部分低代码开发的界面转换为 ArkTS 代码，并修正相关报错后才可以正常编译。代码转换操作会删除 visual 文件及其父目录，且为不可逆过程，代码转换后不能通过 ets 文件反向生成 visual 文件。