DevEco Studio的SDK常见环境问题
=======================

#### 问题现象

*   **场景一**：
    
    在DevEco Studio中下载SDK，出现网络异常该如何解决？
    
*   **场景二**：
    
    应用使用的高版本SDK运行时环境是随应用包分发还是由系统内置，以及如何处理该特性在低版本系统上的运行兼容性风险？
    
*   **场景三**：
    
    代码中引入'@kit.CoreSpeechKit'：
    
    import { speechRecognizer } from '@kit.CoreSpeechKit';
    
    会报错提示：
    
    Cannot find module '@kit.CoreSpeechKit' or its corresponding type declarations. <ArkTSCheck>
    
*   **场景四**：
    
    OpenHarmony 13版本下，无法找到和引入UIExtensionComponent系统接口，且在SDK中也没有找到相关的d.ts文件。
    

#### 背景知识

*   [Command Line Tools](https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos?ha_source=sousuo&ha_sourceId=89000251)集合了HarmonyOS应用开发所用到的系列工具，包括代码检查codelinter、三方库包管理ohpm、命令行解析hstack、编译构建hvigorw。
*   OpenHarmony开发文档参考[OpenHarmony应用开发文档](https://gitee.com/openharmony/docs)。

#### 问题定位

*   **场景一**：
    
    开发者在DevEco Studio工具中尝试下载SDK时出现网络异常问题，可能是由于全局路由服务（Global Routing Service）缓存文件，即位于本地目录“C:\\Users\\用户名\\AppData\\Local\\Huawei\\DevEcoStudio\\caches\\”下的grs.json文件失效。
    
    可能的原因包括但不限于：网络环境异常、路由节点过期、由于DevEco Studio非正常关闭导致grs.json文件损坏。
    
*   **场景二**：
    
    该问题的核心在于应用的编译配置与手机系统版本之间的匹配机制。开发者混淆了“开发环境的SDK版本”与“手机系统的运行库版本”之间的关系，担心高版本特性的依赖项无法在低版本系统中存在。
    
*   **场景三**：
    1.  打开工程的build-profile.json5文件，查看runtimeOS配置的内容，如果配置的是HarmonyOS，需要排查SDK版本是否是HarmonyOS NEXT Developer Preview1之前的版本，该版本将会出现编译报错，因为旧的SDK不支持此类方式导入。
    2.  如果runtimeOS配置的是OpenHarmony，则是正常现象，因为OpenHarmony 5.1.0 Release版本推出的API18，还不支持Core Speech Kit（基础语音服务）的能力，可以通过OpenHarmony应用开发文档查找，发现没有基础语音服务对应的API。
*   **场景四**：
    
    开发者在OpenHarmony 13环境下尝试调用UIExtensionComponent系统接口时，发现开发工具的SDK中缺失该组件相关的.d.ts文件，其根源在于当前工程使用的公共版本SDK（public-SDK），该版本剔除了该接口。
    

#### 分析结论

*   **场景一**：
    
    删除grs.json文件是非常有效的解决方案。删除该文件本质上是迫使工具在下一次启动或者下载时，重新向调度中心发起全局路由请求，重新获取适配当前网络环境的新下载节点，从而打通网络链路。
    
*   **场景二**：
    
    HarmonyOS的SDK的运行库内置于手机系统而非随应用打包，因此应用的兼容性本质上取决于“手机系统版本”是否不低于应用配置的SDK版本；一旦用户系统版本过低，高版本特性将因缺少系统底层支持而导致运行异常。
    
*   **场景三**：
    1.  HarmonyOS工程的SDK版本是HarmonyOS NEXT Developer Preview1之前的版本，该版本将会出现编译报错，因为旧的SDK不支持此类方式导入。
    2.  OpenHarmony工程在API18及以前官方API还不支持基础语音服务的能力。
*   **场景四**：
    
    经分析，UIExtensionComponent仅在提供全量API描述的full-SDK中开放。
    

#### 修改建议

*   **场景一**：
    
    删除“C:\\Users\\用户名\\AppData\\Local\\Huawei\\DevEcoStudio\*\\caches\\”下的grs.json文件。
    
*   **场景二**：
    
    打包后应用的SDK版本，取决于在IDE的File->Project Structure=>Basic Info中的Compatible SDK的版本，安装包是相同的，但是不同用户的手机系统版本可能不同，所以兼容性取决于手机版本和打包时选的SDK版本是否兼容。一般如果打包时选择的SDK版本比较新，建议也同步升级手机系统版本，避免出现不兼容的情况。
    
*   **场景三**：
    1.  针对HarmonyOS工程的SDK版本过低的问题，参考如下修改建议：
        *   如果使用的是DevEco Studio NEXT Developer Preview1至HarmonyOS NEXT Developer Beta1（5.0.3.300）之间的版本，在菜单栏点击Tool > SDK Manager，将SDK更新至HarmonyOS NEXT Developer Preview1及以上版本后，重新进行编译。
        *   如果使用的是HarmonyOS NEXT Developer Beta1（5.0.3.300）及以上的版本，SDK随DevEco Studio软件包安装，无需单独下载，请在下载中心下载并使用新版本DevEco Studio。
    2.  针对OpenHarmony工程，官方API目前还不支持基础语音服务的能力，需要寻找其他替代方案。
*   **场景四**：
    
    OpenHarmony3.2Beta5版本之前可以参考版本说明书手动下载OpenHarmony full-SDK；OpenHarmony3.2Beta5版本及之后不再随版本提供full-SDK包，后续可通过[OpenHarmony每日构建平台](https://ci.openharmony.cn/workbench/cicd/dailybuild/detail/component)，根据分支与日期在每日构建或者滚动构建中查找对应版本的full-SDK。
    
    下载对应版本的full-SDK后替换本地SDK包并重新配置后方可正常使用。
    
    具体可参考：[如何编译full-SDK](https://docs.openharmony.cn/pages/v5.0.3/zh-cn/application-dev/faqs/full-sdk-compile-guide.md)，[如何替换full-SDK](https://docs.openharmony.cn/pages/v5.0.3/zh-cn/application-dev/faqs/full-sdk-switch-guide.md)。