鸿蒙新手入门-环境准备问题解析

Node.js版本与API配套关系

由于SDK的部分工具依赖Node.js运行时，推荐使用配套API版本的Node.js，保证工程的兼容性。

匹配关系见下表：

API Level	Node.js支持范围
API Level≤9	14.x（≥14.19.1）、16.x
API Level>9	14.x（≥14.19.1）、16.x、18.x

ArkTS/JS SDK安装失败处理指导

问题现象

下载ArkTS/JS SDK时，下载失败，提示“Install ArkTS dependencies failed”或“Install JS dependencies failed”。

解决措施

ArkTS/JS SDK下载失败，一般情况下，主要是由于npm代理配置问题，或未清理npm缓存信息导致，可按照如下方法进行处理。

1. 检查网络是否受限，如果需要通过代理才能访问网络，可根据NPM代理配置指导，配置代理服务器信息。如果网络不受限，可跳过该步骤。

2. 请进入到Nodejs的配置目录（默认为C:\Users${userName}\nodejs）下打开命令行工具，执行如下命令，清理npm缓存。

   npm cache clean -f
   

3. 在DevEco Studio欢迎页面， 点击Customize > Configure… > SDK（若已打开工程，可通过工具栏Tools > SDK Manager，进入SDK管理页面），勾选ArkTS/JS SDK，点击Apply重新进行下载。

导入Sample时，提示连接Gitee超时

问题现象

导入Sample时，导入失败，提示“Failed to connect to gitee.com port 443: Time out”连接超时。

解决措施

该问题一般是由于网络受限导致，请检查网络连接状态。如果网络受限，需要通过代理服务器访问网络，请执行以下操作，配置git代理信息。

1. 进入Git安装目录（默认为C:\Program Files\Git），双击运行“git-cmd.exe”文件。

2. 在打开的命令行窗口中，执行以下命令配置代理服务器信息（将proxyUsername、ProxyPassword、proxyserver和port按照实际代理服务器进行修改）。

   说明

   如果password中存在特殊字符，如@、#、*等符号，可能导致配置不生效，建议将特殊字符替换为ASCII码，并在ASCII码前加百分号%。常用符号替换为ASCII码对照表如下：

   • !：%21
   • @：%40
   • #：%23
   • $：%24
   • &：%26
   • *：%2A

   git config --global http.proxy http://proxyUsername:[email protected]:port
   

3. 执行完成后，请重新尝试导入Sample。

导入Sample时，提示SSL证书校验错误

问题现象

导入Sample时，导入失败，提示“SSL certificate problem: unable to get local issuer certificate”证书校验错误。

解决措施

出现这个错误可能是网络遭受了攻击，或者你的网络提供方网络策略阻止了相关操作，如果你确认所处的网络环境安全，可以临时关闭证书校验以获取Sample。

1. 进入Git安装目录（默认为C:\Program Files\Git），双击运行“git-cmd.exe”文件。

2. 在打开的命令行窗口中，执行如下命令关闭SSL证书校验功能。

   说明

   关闭SSL证书校验，可能会带来安全风险，建议导入完Sample后，及时开启。开启方法：将该命令中的false修改为true即可。

   git config --global http.sslVerify false
   

3. 执行完成后，请重新尝试导入Sample。

下载HarmonyOS SDK时提示网络连接错误

问题现象

网络连接正常，下载HarmonyOS SDK时，却提示网络连接错误。

解决措施

可能因为使用的PC的系统语言是英文，区域码是US所致。按照以下方式，将区域码修改为CN，在修改前请先关闭DevEco Studio。

在 C:\Users*username*\AppData\Roaming\Huawei\DevEcoStudio3.0\options 路径下(MacOS路径为/Users/username/Library/Application Support/Huawei/DevEcoStudio3.0/options)，打开 country.region.xml ，修改countryregion name为“CN”。

下载SDK时弹窗提示“python3”命令需要使用命令行开发者工具

问题现象

在Mac上，下载SDK时在执行npm install过程中，弹出提示“‘python3’命令需要使用命令行开发者工具”，install暂停。

解决措施

如果使用的Node版本为16.x，可能会由于在npm执行install命令安装SDK中的某些依赖包时，依赖python3执行node-gyp命令，从而导致弹窗提示需要安装python3，此时请点击安装即可。

DevEco Studio无法打开

问题现象

在Windows 10和Windows 11中，修改字符编码后，安装在中文目录下的DevEco Studio无法打开，报错“Error launching…”。

解决措施

请在英文目录下重新安装DevEco Studio。

如何配置DevEco Studio的代理

DevEco Studio开发环境依赖于网络环境，需要连接上网络才能确保工具的正常使用。

一般来说，如果使用的是个人或家庭网络，是不需要设置代理信息的；只有部分企业网络受限的情况下，才需要设置DevEco Studio的代理信息。

1. 打开File > Settings > Appearance & Behavior > System Settings > HTTP Proxy配置界面。

2. 勾选Manual proxy configuration，设置DevEco Studio的HTTP Proxy。

   • HTTP配置项，设置代理服务器信息。如果不清楚代理服务器信息，可以咨询你们的网络管理人员。

     • Host name：代理服务器主机名或IP地址。
     • Port number：代理服务器对应的端口号。
     • No proxy for：不需要通过代理服务器访问的URL或者IP地址（地址之间用英文逗号分隔）。

   • Proxy authentication配置项，如果代理服务器需要通过认证鉴权才能访问，则需要设置。否则，请跳过该配置项。

     • Login：访问代理服务器的用户名。
     • Password：访问代理服务器的密码。
     • Remember：勾选，记住密码。

   

3. 配置完成后，点击Check connection，输入网络地址，检查网络连通性。提示“Connection successful”表示代理设置成功。然后点击OK按钮完成配置。

安装npm包失败的处理办法

问题现象

在执行npm install命令安装npm仓时，提示安装失败。

解决措施

可能是由于未设置npm仓的地址，可执行如下命令后进行重新安装。

npm config set @ohos:registry=https://repo.harmonyos.com/npm/

如何安装及更新ohpm

问题现象

在DevEco Studio中如何安装及更新ohpm版本。

解决措施

1. 进入ohpm路径配置界面。

   • 在欢迎页单击Configure （或图标） > Settings > Build, Execution, Deployment > Ohpm > ohpm home > edit， 进入ohpm路径配置界面（macOS为Configure > Preferences > Build, Execution, Deployment > Ohpm > ohpm home > edit）。
   • 在打开了工程的情况下，可以单击File > Settings > Build, Execution, Deployment > Ohpm > ohpm home > edit，进入ohpm路径设置界面（macOS为DevEco Studio > Preferences > Build, Execution, Deployment > Ohpm > ohpm home > edit）

2. 点击Install按钮，选择一个空目录，点击Next按钮，安装ohpm最新版本。

   

如何在命令行使用ohpm

问题现象

安装ohpm之后，不能直接在命令行中使用ohpm。

解决措施

1. 将ohpm安装bin目录，添加至环境变量中。

   

2. 添加完变量后重开命令行窗口，执行ohpm -v查看ohpm版本号，终端输出版本号信息（如1.0.0）即为成功。

   

环境检查时显示ohpm registry access不通过

ohpm registry access不通过可能有以下几种情况：

问题现象 1

registry地址校验连接不通过，详细信息提示“check whether the ohpm repository is correctly set”。

解决措施

• 场景一：可能是配置的registry错误，请点击提示中"Click here"，检查registry配置是否正确或配置新的registry地址。

• 场景二：可能是ohpm版本不匹配，请将ohpm更新至最新版本。具体操作请参考如何安装及更新ohpm章节。

• 场景三：可能是网络不通，需要配置代理。可采用以下两种操作进行配置：

  方法1：点击提示中"Click here"，进入代理配置界面，进行HTTP proxy配置；

  方法2：修改“C:\users\用户名.ohpm”目录下的 .ohpmrc文件（如果该目录下没有 .ohpmrc文件，请新建一个），修改http_proxy或https_proxy配置项。

  如果代理服务器需要认证（需要用户名和密码），请根据如下指导配置代理服务器的用户名和密码信息。

  1. 进入C:\Users\用户名目录.ohpm，打开 .ohpmrc文件。如果该目录下没有 .ohpmrc文件，请新建一个。

  2. 修改ohpm代理信息，在http_proxy和https_proxy中，增加user和password字段，具体取值请以实际代理信息为准。示例如下所示：

     http_proxy=http://u se r:password@ proxy.server.com:80https_proxy=http://user:password@ proxy.server.com:80
     

     说明

     1. 如果password中存在特殊字符，如@、#、*等符号，可能导致配置不生效，建议将特殊字符替换为ASCII码，并在ASCII码前加百分号%。常用符号替换为ASCII码对照表如下：
     • !：%21
     • @：%40
     • #：%23
     • $：%24
     • &：%26
     • *：%2A

  3. 代理配置完成后，打开命令行工具，执行如下命令验证网络是否正常。

     ohpm info @ohos/lottie
     

     执行结果如下图所示，则说明代理设置成功。

     

问题现象 2

registry证书地址校验不通过，详细信息提示“UNABLE_TO_VERIFY_LEAF_SIGNATURE”。

解决措施

该问题可能是校验registry证书时出现问题。

进入C:\Users\用户名目录.ohpm，打开 .ohpmrc文件。如果该目录下没有 .ohpmrc文件，请新建一个。

• 将registry对应的证书地址，配置在ca_files字段中（多个证书路径采用英文逗号分隔）

  ca_files=your_ca_files_path
  

• 或者配置strict_ssl=false，暂时屏蔽证书校验

  strict_ssl=false
  

  说明

  屏蔽证书校验，可能会带来安全风险，请确认屏蔽证书校验风险后再修改配置，建议使用完成后及时开启。开启方法：将该配置中的false修改为true即可。

环境检查时显示npm registry access不通过

npm registry access不通过可能有以下几种情况：

问题现象 1

registry地址校验连接不通过，详细信息提示“check whether the npm repository is correctly set”。

解决措施

场景一：可能是配置的registry错误。请检查registry配置是否正确，或点击提示中"Click here"，勾选并配置新的registry地址。

场景二：可能是网络不通，需要配置代理。可采用以下两种方式进行配置：

方式1：点击提示中"Click here"，进入代理配置界面，勾选npm registry项和ohos registry项，并完成HTTP proxy配置；

说明

若您的代理服务器需要认证（需要用户名和密码），请参考方式2进行配置。

方式2：修改“C:\users\用户名”目录下的 .npmrc文件（如果该目录下没有 .npmrc文件，请新建一个），修改http_proxy或https_proxy配置项。

如果代理服务器需要认证（需要用户名和密码），请根据如下指导配置代理服务器的用户名和密码信息。

1. 进入C:\Users\用户名目录，打开 .npmrc文件。如果该目录下没有 .npmrc文件，请新建一个。

   

2. 修改npm仓库信息，示例如下所示：

   registry=https://repo.huaweicloud.com/repository/npm/@ohos:registry=https://repo.harmonyos.com/npm/
   

3. 修改代理信息，在proxy和https-proxy中，将user、password、proxyserver和port按照实际代理服务器进行修改。示例如下所示：

   proxy=http://user:password @ proxy.proxyserver.com:porthttps-proxy=http://user:password @ proxy.proxyserver.com:port
   

   说明

   如果password中存在特殊字符，如@、#、*等符号，可能导致配置不生效，建议将特殊字符替换为ASCII码，并在ASCII码前加百分号%。常用符号替换为ASCII码对照表如下：

   • !：%21
   • @：%40
   • #：%23
   • $：%24
   • &：%26
   • *：%2A

4. 将Node.js配置到环境变量中。

   • Windows环境变量设置方法：

     • 在此电脑 > 属性 > 高级系统设置 > 高级 > 环境变量中，在系统或者用户的PATH变量中，添加Node.js安装位置的路径。

   • macOS环境变量设置方法：

     打开终端工具，执行以下命令。

     export NODE_HOME=/home/xx/Downloads/node-vxx.xx.x-linux-x64  #本处路径请替换为Node的安装路径export PATH=${NODE_HOME}/bin:${PATH}
     

5. 代理配置完成后，打开命令行工具，执行如下命令验证网络是否正常。

   npm info express
   

   执行结果如下图所示，则说明代理设置成功。

   

问题现象 2

registry证书地址校验不通过，详细信息提示“UNABLE_TO_VERIFY_LEAF_SIGNATURE”。

解决措施

该问题可能是校验registry证书时出现问题。

进入C:\Users\用户名目录，打开 .npmrc文件。如果该目录下没有 .npmrc文件，请新建一个。

• 将registry对应的证书地址，配置在cafile字段中（多个证书路径采用英文逗号分隔）。

  cafile=your_ca_files_path
  

• 或者配置strict-ssl=false，暂时屏蔽证书校验。

  strict-ssl=false
  

  说明

  屏蔽证书校验，可能会带来安全风险，请确认屏蔽证书校验风险后再修改配置，建议使用完成后及时开启。开启方法：将该配置中的false修改为true即可。