鸿蒙PC Electron 开发环境搭建指南

结局无敌

1050人浏览 · 2025-11-25 19:20:24

结局无敌 · 2025-11-25 19:20:24 发布

鸿蒙PC Electron 开发环境搭建指南

核心要点：工具链版本精准匹配

鸿蒙PC Electron 开发环境的成功搭建，高度依赖于 Node.js、DevEco Studio 和鸿蒙 Electron 脚手架三者的版本严格匹配。任何版本不兼容都可能导致 SDK 下载失败、安装错误或项目崩溃等一系列问题。本指南专为 鸿蒙PC（HarmonyOS for PC） 应用开发场景设计，针对 Windows 11 和 macOS Sonoma 系统提供详细搭建教程，并附上权威的版本匹配表和常见问题解决方案，助您快速迈入鸿蒙PC生态开发的大门。

一、版本匹配原则

开发鸿蒙PC Electron 应用，必须确保以下工具使用指定版本（截至2025年11月最新稳定版）：

工具名称	Windows 版本	macOS 版本	主要功能
Node.js	v16.20.2 (LTS)	v16.20.2 (LTS)	提供 JavaScript 运行时环境
DevEco Studio	4.1.3.500	4.1.3.500	鸿蒙官方集成开发环境（IDE）
鸿蒙 Electron 脚手架	`@hmos/electron-cli@1.2.0`	`@hmos/electron-cli@1.2.0`	用于创建和构建鸿蒙PC项目
HarmonyOS SDK	API Version 12	API Version 12	提供鸿蒙PC系统API支持

重要提示：切勿盲目追求最新版本！

Node.js 高于 v16.20.2 会导致脚手架依赖冲突。

DevEco Studio 低于 4.1 版本无法支持 API Version 12，而该版本是鸿蒙PC应用开发的基石。

二、Windows 11环境搭建

2.1 Node.js安装与配置

访问 Node.js 官方历史版本存档。
根据您的系统架构下载安装包：
- 64位系统：node-v16.20.2-x64.msi
- 32位系统：node-v16.20.2-x86.msi
安装时务必勾选 "Add to PATH" 选项，以确保命令行能全局访问 node 和 npm。

2.2 DevEco Studio安装与配置

从华为开发者官网下载 4.1.3.500 版本的 DevEco Studio。
安装时选择默认路径并创建桌面快捷方式。
首次启动配置：
- 选择安装路径（建议保持默认）。
- 在 SDK 安装界面，必须勾选以下组件：
  - API Version 12 > SDK Platform
  - API Version 12 > Toolchains
  - API Version 12 > JS/Native SDK

配置环境变量：
将以下两个路径添加到系统的 Path 环境变量中，以便在任意位置调用鸿蒙构建工具。

C:\Users\<您的用户名>\AppData\Local\Huawei\Sdk\toolchains\hvigor\bin
C:\Users\<您的用户名>\AppData\Local\Huawei\Sdk\toolchains\nodejs\bin

2.3 脚手架安装

打开命令提示符（CMD）或 PowerShell，执行以下命令全局安装鸿蒙PC Electron 脚手架：

npm install -g @hmos/electron-cli@1.2.0

2.4 创建并运行项目

在桌面或其他工作目录下，执行以下命令创建新项目：
```
hmos-electron create first-harmony-pc-electron
```
进入项目目录并启动开发服务器：
```
cd first-harmony-pc-electron
npm run dev
```
项目成功运行后，鸿蒙PC模拟器将启动并显示 "Hello HarmonyOS Electron" 界面，标志着您的开发环境已初步就绪。

三、macOS Sonoma 系统环境搭建步骤（详细版）

macOS 环境搭建逻辑与 Windows 一致，但需特别注意系统权限和路径差异。

3.1 步骤 1：安装 Node.js 并配置镜像

1.1 下载并安装 Node.js

访问 Node.js v16.20.2 下载 .pkg 安装包并完成安装。

1.2 验证安装并配置镜像

打开终端，验证安装：

node -v # 应输出 v16.20.2
npm -v  # 应输出对应版本号

为加速依赖下载，可配置 npm 镜像源（可选但推荐）：
```
npm config set registry https://registry.npmmirror.com
```

3.2 步骤 2：安装 DevEco Studio 并配置 SDK

2.1 下载并安装 DevEco Studio

从华为开发者官网下载 4.1.3.500 版本的 macOS 安装包（.dmg 文件），拖拽至 Applications 文件夹完成安装。

2.2 首次启动并配置 SDK

首次启动 DevEco Studio 时，同样需要安装 API Version 12 的全部必要组件（SDK Platform, Toolchains, JS/Native SDK）。

2.3 配置环境变量

打开终端，编辑您的 shell 配置文件（如 ~/.zshrc 或 ~/.bash_profile），添加以下内容：

export PATH="$PATH:$HOME/Library/Application Support/Huawei/Sdk/toolchains/hvigor/bin"
export PATH="$PATH:$HOME/Library/Application Support/Huawei/Sdk/toolchains/nodejs/bin"

保存文件后，执行 source ~/.zshrc（或对应文件）使配置生效。

3.3 步骤 3：安装脚手架并创建项目

与 Windows 步骤一致，在终端中执行以下命令：

# 安装脚手架
sudo npm install -g @hmos/electron-cli@1.2.0

# 验证版本
hmos-electron -v

# 创建项目
cd ~/Desktop
hmos-electron create first-harmony-pc-electron

# 启动项目
cd first-harmony-pc-electron
npm run dev

启动成功后，鸿蒙PC模拟器会显示项目界面，macOS 环境搭建完成。

四、通用避坑清单：解决 90% 环境搭建问题

4.1 常见安装报错及解决方案

报错现象	报错原因	解决方案
DevEco Studio 下载 SDK 时提示“网络连接失败”	网络防火墙拦截，或默认镜像源访问受限	1. 关闭系统防火墙和杀毒软件； 2. 手动配置 SDK 镜像：`File > Settings > Appearance & Behavior > System Settings > HarmonyOS SDK > SDK Update > 勾选“Customize repository”`，输入镜像地址 `https://mirrors.huaweicloud.com/harmonyos/sdk`，点击“Apply”后重新下载。
安装脚手架时提示“permission denied”	系统权限不足，npm 无全局安装权限	Windows：以管理员身份打开命令提示符后重新安装； macOS：在命令前加 `sudo` 授权，即 `sudo npm install -g @hmos/electron-cli@1.2.0`，输入系统密码后执行。
执行 `hmos-electron` 命令提示“不是内部或外部命令”	Node.js 全局模块路径未加入环境变量	1. 执行 `npm root -g` 获取全局模块路径； 2. 将该路径（如 Windows: `C:\Users\用户名\AppData\Roaming\npm`；macOS: `/usr/local/bin`）添加到系统环境变量 `Path` 中，重启终端后重试。
启动项目时提示“Cannot find module 'xxx'”	项目依赖安装不完整，或依赖版本冲突	1. 进入项目目录，删除 `node_modules` 文件夹和 `package-lock.json` 文件； 2. 重新执行 `npm install` 安装依赖； 3. 若仍报错，执行 `npm cache clean --force` 清理缓存后重新安装。
模拟器启动失败，提示“未检测到可用设备”	DevEco Studio 未安装模拟器组件，或模拟器服务未启动	1. 安装模拟器组件：`Tools > Device Manager > Install Emulator`； 2. 启动模拟器：在 Device Manager 中点击 `New Emulator`，选择 “Phone” 类型（当前鸿蒙PC模拟器基于此类型），下载 HarmonyOS 4.0 镜像，创建后点击 `Start` 启动。

4.2 环境搭建成功验证标准

完成搭建后，需确保以下 4 点验证通过，才算环境完全正常：

命令行验证：在终端/命令行中执行 node -v、npm -v、hmos-electron -v 均能正确返回版本号。
IDE 验证：DevEco Studio 能正常启动，且 Device Manager 中能看到已创建的模拟器设备。
项目创建验证：能成功执行 hmos-electron create 命令，无报错地生成新项目。
项目运行验证：进入项目目录执行 npm run dev 后，模拟器能成功启动并显示应用界面。

五、后续操作：项目打包与真机调试

环境搭建成功后，即可进行后续的打包和真机调试操作，为鸿蒙PC应用的正式部署做准备：

打包：通常使用 npm run build 命令生成可分发的 .hap 文件。
真机调试：需在真机上开启开发者模式，并通过 DevEco Studio 的 Run 按钮将应用直接部署到连接的鸿蒙PC设备上。

后续开发建议：将常用命令（如创建、启动、打包）整理为脚本（Windows 的 .bat 文件、macOS 的 .sh 文件），避免重复输入；同时定期备份 package.json 文件，确保依赖版本可追溯。

六、总结

鸿蒙PC Electron 开发环境搭建的核心在于 “版本严格匹配” 和 “环境变量正确配置”。Windows 和 macOS 系统的搭建逻辑高度一致，差异仅在于安装包格式和环境变量路径。遇到问题时，优先对照本指南的“避坑清单”进行排查，90% 的问题都能通过版本调整、镜像配置、权限授权等手段得到解决。

一旦环境搭建成功，您便可以充分利用现有的 Web 技术栈（HTML, CSS, JavaScript），结合 Electron 的强大能力，高效地开发出高性能、高体验的鸿蒙PC原生应用，真正实现 “一次开发，多端部署” 的鸿蒙生态核心价值。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/
在这里，您可以获取最新的技术文档、参与开发者讨论、分享您的鸿蒙PC应用开发经验，并与社区一同推动国产操作系统生态的繁荣发展！