# 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文件。
    
*   场景五：
    
    在DevEco Studio 3.1 Release版本中下载API 7 SDK时失败，提示"Could not found download URL, the network or server is abnormal"。
    
*   场景六：
    
    在build-profile.json5文件中配置"runtimeOS": "OpenHarmony"后，DevEco Studio中UI层报错。
    

#### 背景知识

*   Command Line Tools集合了HarmonyOS应用开发所用到的系列工具，包括代码检查codelinter、三方库包管理ohpm、命令行解析hstack、编译构建hvigorw。
*   OpenHarmony开发文档参考OpenHarmony应用开发文档。

#### 问题定位

*   场景一：
    
    开发者在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），该版本剔除了该接口。
    
*   场景五：
    
    当前已不再维护该历史版本，API 7 SDK在外网无对外下载地址，导致DevEco Studio无法获取有效的下载链接。
    
*   场景六：
    
    检查已下载的SDK文件，发现缺失component\_config.json文件，导致DevEco Studio无法正确解析UI组件配置信息，从而出现UI层报错。
    

#### 分析结论

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

#### 修改建议

*   场景一：
    
    删除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每日构建平台，根据分支与日期在每日构建或者滚动构建中查找对应版本的full-SDK。
    
    下载对应版本的full-SDK后替换本地SDK包并重新配置后方可正常使用。
    
    具体可参考：如何编译full-SDK，如何替换full-SDK。
    
*   场景五：
    
    可通过以下链接手动下载API 7 SDK，下载后将SDK文件放置于SDK目录hmscore\\3.0.0\_7下，刷新后查看SDK是否正常显示。
    
    macOS版本下载链接：
    
    *   ets-darwin-3.0.0.5-Release.zip。
    *   java-darwin-3.0.0.5-Release.zip。
    *   js-darwin-3.0.0.5-Release.zip。
    *   native-darwin-3.0.0.5-Release.zip。
    *   previewer-darwin-3.0.0.5-Release.zip。
    *   toolchains-darwin-3.0.0.5-Release.zip。
    
    如需下载Windows版本，将链接中的"darwin"替换为"Windows"即可。
    
    下载完成后，建议通过SHA256校验文件的完整性和未被篡改。在终端中执行以下命令：
    
    ```
    sha256sum 文件名
    ```
    
    例如：
    
    ```
    sha256sum toolchains-darwin-3.0.0.5-Release.zip
    ```
    
    各文件对应的SHA256校验值如下：
    
    *   ets-darwin-3.0.0.5-Release.zip：c5746362f369858591edc599d973b1667f313045f21eda6f62efe167eb72374a。
    *   java-darwin-3.0.0.5-Release.zip：d202f16f9db4a691c94d298e05cb267ba474f585766440e772e64d59765d9550。
    *   js-darwin-3.0.0.5-Release.zip：7f4d92bbc1934cd6d0da26554678a3b92dbb030d8fc1c8d438786ec89cd34e12。
    *   native-darwin-3.0.0.5-Release.zip：69c56b186b68bfec7d282270c358c6986000679c93fb75a718229ba89a706f7f。
    *   previewer-darwin-3.0.0.5-Release.zip：ac0671e86060a9d13349b82ebfc070420a1905787f72dfe971d770f0107a035f。
    *   toolchains-darwin-3.0.0.5-Release.zip：055020680a6c509fa9a9f9afaa9813760d6338dea190104601dffe6dc6743121。
    
*   场景六：
    
    重新卸载并安装SDK，确保SDK文件完整后重新编译工程。