如何解决DevEco Studio的Sync异常问题

1.1 概述

Sync（同步）过程是使用DevEco Studio进行HarmonyOS 应用开发的必备步骤之一。打开工程时会自动进行Sync，切换分支、修改依赖时会提示进行Sync，您也可以在菜单中点击“Sync and Refresh Project”手动触发Sync。在Sync过程中，您可能遇到过Sync异常的情况，出现异常时可能会导致IDE的行为不符合预期，如高亮异常，三方库安装失败等。

本文旨在介绍Sync涉及的场景，可能出现异常的原因，以及如何在出现异常后快速恢复。

1.2 Sync 流程

DevEco Studio是基于IntelliJ IDEA开源底座打造，用于HarmonyOS 应用开发的IDE。在Sync过程中除了IntelliJ IDEA底座原生的初始化及索引构建外，还会进行工程相关的工程解析、依赖解析及下载安装（ohpm install）、编译构建初始化（hvigor）、ArkTS语言索引构建、C++索引构建等。主要流程如下图所示

1.3 探索Sync异常的原因及快速恢复方法

1.3.1 底座/工程管理

IntelliJ IDEA底座具有强大的搜索能力，能够支持基于文本的快速搜索，而高效搜索得益于Sync过程中完成的PSI等索引的构建及复杂的VFS文件系统。

在Sync过程中，底座需要构建文件索引。当项目规模较大、依赖关系复杂时，索引构建过程会产生显著的性能开销。如果索引缓存文件或VFS系统出现损坏，Sync过程可能会卡在某些文件的索引上，出现长达几个小时的索引构建。

      说明：

常见异常场景及复原手段：

大型工程切换分支后，进度条卡在Updating indexes无法退出

• Updating indexes阶段，底座VFS会对文件构造索引。对于依赖复杂的大型工程，oh_modules的文件树层级复杂，软链接文件数量多，在切换分支时，涉及大量文件的增删时可能会出现索引异常。

可清除底座索引后重启：菜单栏File->Invalidate Caches…，全选并点击Invalidate and Restart。

• 如果是索引卡在某个文件，可以将该文件排除索引：右键该文件->选择Override File Type->Plain Text。

• 如果某个文件夹嵌套很深或文件夹中文件数量很多，底座索引需要显著的时间开销，导致一直在索引该文件夹中的文件。

如果不需要关注某文件夹，可排除此文件夹的索引：在该工程目录的.idea/modules/工程名.iml中添加（若无对应文件，可能为工程首次打开，重启IDE即可）。

1.3.2 ohpm

Sync过程中ohpm会对工程的依赖进行解析并下载安装（ohpm install）。ohpm install过程中，ohpm会根据配置的中心仓地址下载对应版本的依赖包。

       说明：

常见异常场景及复原手段：

Sync过程的ohpm install阶段持续运行，存在未释放的网络连接，导致install无法退出

• 6.0.1 release版本已修复。
• 之前的版本可通过重新Sync恢复：File->Sync and Refresh Project。

1.3.3 hvigor

Sync过程中，hvigor需要完成初始化，以及执行hvigor的生命周期hook点上挂接的任务。

      说明：

常见异常场景及复原手段：

1. 有多个C++模块的工程Sync时，hvigor脚本执行多次，导致Sync时间过长

带有C++模块的工程在Sync时，会在完成Build Init（hvigor初始化）后进行C++模块的索引建立。每个C++模块都会通过hvigor执行一次compileNative，每次compileNative会执行一遍hvigor脚本（如图，有两个C++模块，hvigor脚本执行了三次）。

如果hvigor脚本的执行逻辑与C++模块编译无关，如以下场景：

• 采用hvigor脚本统计工程信息，无需多次执行脚本，此时可考虑采用此手段，减少运行次数；
• 采用hvigor脚本动态修改C++模块的配置信息，需要在每个C++模块都执行修改，此时每个C++模块都需要执行hvigor脚本，不能进行执行逻辑的跳过；

则可以在hvigor脚本中使用**!hvigor.isCommandEntryTask(‘compileNative’)** 判断跳过该执行逻辑。修改后示例如下：

代码4-6行添加了**!hvigor.isCommandEntryTask(‘compileNative’)** 的判断后，console.log(‘test’)的日志在compileNative模块不会被执行。

2. hvigor脚本里使用了setDependenciesOpt等接口修改依赖，Sync时，执行两次ohpm install，影响性能

Sync时，在hvigor初始化之前会进行一次ohpm install，为了支持开发者能够灵活调整依赖关系，hvigor提供接口setDependenciesOpt，支持开发者进行扩展。若通过setDependenciesOpt修改了依赖，则hvigor会在setDependencies进行ohpm install增量安装。在setDependenciesOpt中定制依赖较多的工程中，第二次ohpm install增量安装对性能有较大影响。

hvigor采用“Enable ohpm execution by hvigor”开关支持ohpm install合一，优化性能。“Enable ohpm execution by hvigor”打开后，ohpm install会统一在hvigor的setDependencies中调用，减少一次增量ohpm install，优化性能。

开启方式：

“File->Settings->Build, Execution, Deployment->Build Tools->Hvigor->Enable ohpm execution by hvigor”开关

结果如下：

开启开关后，console中只有Build Init阶段，没有独立的ohpm install阶段。

1.3.4 ArkTS/C++ LSP

DevEco Studio的ArkTS及C++语言服务能力基于**Language Server Protocol (LSP)**架构，IDE进程作为LSP Client，同时拉起LSP Server进程独立提供处理语言的能力，如符号跳转、联想等。因此，在Sync过程，ArkTS Server及C++ Server会进行索引的构建。

ArkTS的LSP Server基于Node运行时，而C++的LSP Server基于Clangd，您在使用IDE过程中会看到独立的Node进程与Clangd进程。

      说明：

常见异常场景及复原手段：

1. 打开代码量较大的工程时，右下角提示报错“ArkTS language service terminated due to memory constraints”，且代码跳转等语言服务能力失效

当DevEco Studio打开项目工程时，ArkTS会启动LSP Server进程扫描工程代码以建立索引。当LSP Server进程内存占用超过内存上限时，LSP Server进程会启动失败，从而报错 “ArkTS language service terminated due to memory constraints”。LSP Server进程默认内存上限为8G。

为避免工程代码量过大导致语言服务启动失败，请根据工程代码量和开发环境内存大小配置合适的LSP Server进程内存上限。以配置内存上限为12G举例，打开DevEco Studio，通过菜单栏的Help > Edit Custom Properties…，打开idea.properties配置文件。在文件中新增一行arkts.server.max.old.space.size=12288，然后重启DevEco Studio。LSP Server进程的内存上限将设置为12288M（即12G）。

**注意：**并非所有工程都应该配成12G，内存上限值需要随工程的代码量和复杂程度增长，可根据具体情况适当增减。

2. 通过“Just restart”的方式重启IDE，“Scaning files to index”进度条耗时较久

关闭DevEco Studio时，LSP Server进程会收集并落盘索引缓存信息。当工程较大或比较复杂时，索引信息落盘会比较耗时。通过“Just restart”重启会在关闭后立即重启IDE，此时索引信息还未落盘完毕，因此多个Server进程同时运行，内存、磁盘IO会有额外占用，导致编辑器初始化索引性能下降，“Scaning files to index”耗时大幅增加。

为避免重启后同时存在多个Node进程占用内存与磁盘IO，在需要重启时请使用DevEco Studio菜单栏的File > Invalidate Caches… > Invalidate and Restart功能。后续API24（6.1.1）版本会优化该问题。