鸿蒙 PC 上做 Electron 开发，到底要装哪些东西？——一份"装完就能 Run"的最短路径指南

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

这不是教你"什么是 Electron"。

这是给已经决定在鸿蒙 PC 上做 Electron 应用的开发者准备的：到底需要装哪些东西、按什么顺序装、哪些不装会卡你半天、哪些以为要装其实不用。

写完测过 3 遍，照做能从"零环境"到"在鸿蒙 PC 上看到 Electron 窗口"。

在这里插入图片描述

这篇给谁看

你符合下面任一条 → 接着读
✅ 鸿蒙 DevEco 已经装好，但想做 Electron 应用不知道还要装什么
✅ 看过别人写的 Electron 鸿蒙跑通教程，但没说清楚 libelectron 和普通 Electron 有啥区别
✅ 在 npm 装 Electron 装了半天，才发现根本用不上

不适合：

一、先纠正最常见的认知错误

很多人第一次想"在鸿蒙 PC 上写 Electron 应用"，第一反应是：

npm install electron

这是错的。

或者更准确地说——这件事你会做，但它跟"鸿蒙 PC 上的 Electron"是两回事。

桌面 Electron 和鸿蒙 Electron 的关系

维度 桌面 Electron（你熟悉的那个） 鸿蒙 Electron（libelectron）
Electron 来源 npm install 来 官方/社区预编译的 .so + 资源包
运行环境 你本机 macOS/Windows/Linux 鸿蒙 PC 真机
主进程 electron . 启动 鸿蒙 EntryAbility 里的 WebAbility 加载
渲染层 Chromium 同样是 Chromium（libelectron 内嵌）
package.json 用 完整使用 只用 main + 业务依赖，不用安装 electron 本体

关键洞察：

鸿蒙 PC 上的 Electron 运行时是宿主提供的（在 libelectron.so 里），不需要、也不能从 npm 安装。

你的 package.json 里写了 dependencies: { "electron": "..." } 反而会出问题——参考 《Electron 鸿蒙 PC 适配 FAQ #11》。

那 npm 装 Electron 完全没用吗？

也不是——本机装 Electron 只在两种场景下需要：

  1. 本机开发期验证：先用 electron . 在 macOS/Windows 上跑起来确认逻辑没问题，再搬到鸿蒙
  2. 写主进程代码补全用：IDE 需要 node_modules/electron/ 里的类型定义才能给你 app.whenReady() 这类 API 的智能提示

所以本机的 Electron 是开发辅助，不是运行时。这个概念想通了，下面的安装顺序就好理解了。

二、一份完整的清单（建议打印贴显示器边上）

按"必装/选装"分两档：

🟦 必装（不装就根本干不了）

工具 版本 装在哪 体积 用来干嘛
鸿蒙基础环境 DevEco 5.0+ / SDK API 17+ 本机 ~12 GB 见前一篇文章
Node.js 20.18.1（重要） 本机 20 MB 跑 npm / hvigor 构建
OHPM 跟 DevEco 走 本机 20 MB 鸿蒙包管理（前一篇也讲过）
libelectron 预编译包 新版双模块 Electron 37.x 解压到工程目录 ~2 GB 鸿蒙 Electron 运行时
hdc 跟 SDK 走 加 PATH - 真机调试

🟨 强烈建议装（不装会很难受）

工具 用来干嘛
本机 Electron（npm 装） 开发期本地跑前端 / IDE 类型提示
VS Code + Volar/Vetur 写前端 Vue/React 比 DevEco 顺手
gh / git-lfs 拉 libelectron 包动辄 1-2 GB

🟥 看起来好像要装、其实不要装

工具 为什么不装
electron-builder 鸿蒙打包走 DevEco hvigor 流程，不用 electron-builder
electron-packager 同上
@electron/remote 鸿蒙 Electron 默认禁用 remote 模块（参考 FAQ #17）
keytar / node-keytar 鸿蒙没系统密钥链，必须 mock
native-keymap 鸿蒙没对应实现
任何 *-native *.node 模块 musl libc + aarch64 几乎都要重编（劝退）

三、按顺序装（30 分钟流程）

下面按"如果今晚我重装一遍会怎么做"的最优顺序：
在这里插入图片描述

步骤 1：先确认鸿蒙基础环境已就位（5 分钟）

在这里插入图片描述

快速 self-check：

# 1) DevEco 能打开
ls /Applications | grep -i deveco   # macOS
# 或 Windows 的开始菜单有 DevEco

# 2) hdc 在 PATH
which hdc
hdc -v        # 应该输出 Ver: 3.x

# 3) SDK 装好了
ls ~/Library/Huawei/Sdk/openharmony/   # macOS
# 应该看到 17/ 20/ 23/ 等目录

# 4) Node 是 20.x
node -v       # 应该 v20.18.1

全部通过再往下。任何一个 No 都先回上一篇补齐。

步骤 2：本机装 Electron（5 分钟）

虽然鸿蒙运行时不用 npm 的 Electron，但开发期辅助用：

# 推荐用 nvm 切到 Node 20
nvm use 20.18.1

# 找个空目录初始化
mkdir ~/dev/electron-playground && cd ~/dev/electron-playground
npm init -y

# 装 Electron 本身（注意是 --save-dev 不是 --save）
npm install --save-dev electron@37

# 验证
npx electron --version    # 应该输出 v37.x.x

⚠️ 为什么是 Electron 37：

鸿蒙 libelectron 新版（双模块）打包的 Chromium 是 Electron 37。本机用 37 写代码，和鸿蒙运行时 API 一致——避免你在本机写了 38 才有的 API、搬到鸿蒙跑不了。

步骤 3：下载 libelectron 预编译包（10-20 分钟，取决于带宽）

这是鸿蒙 Electron 真正的"运行时"。两个版本要分清楚：

版本 解压后根目录 适用设备
旧版（5.0.x XComponent） 直接 AppScope/ electron/ build-profile.json5 HarmonyOS 5.0.x（API 15-17）
新版（Electron 37 双模块） 多一层 ohos_hap/ HarmonyOS 6.0+（API 20+）

怎么选：

# 看你的设备 ROM
hdc shell param get const.product.software.version
# 输出 6.x.x 的 → 一定要用新版
# 输出 5.0.x 的 → 旧版也行，但建议直接用新版（向上兼容）

下载渠道：

  • 官方仓库 openharmony-sig/electron 的 Release 页面
  • 鸿蒙开发者社区交流（淼学派对等社区有镜像）
    在这里插入图片描述

包体积：约 1.5-2 GB。首次下载建议挂着去吃午饭。

解压后核心目录长这样（新版）：

libelectron/
  └─ ohos_hap/                              ← 这一层！
      ├─ AppScope/
      ├─ electron/                          ← entry 模块
      │   └─ libs/arm64-v8a/
      │       ├─ libelectron.so   (169 MB)  ← Chromium 132 + Electron 37 全在里头
      │       ├─ libffmpeg.so
      │       ├─ libc++_shared.so
      │       └─ libadapter.so
      ├─ web_engine/                        ← HSP 模块
      │   └─ src/main/resources/
      │       └─ resfile/
      │           └─ resources/app/         ← ★ 你的 main.js 放这里 ★
      ├─ build-profile.json5
      └─ oh-package.json5

新版的关键认知：

真正的 Electron 运行时 + Chromium 全部打包进 libelectron.so（169 MB 那个大块头）。

你写的 main.js 只是被它加载的"应用代码"——和 macOS 上 Electron.app/Contents/Resources/app/main.js 是同一个角色。

步骤 4：DevEco 打开 ohos_hap 子目录（5 分钟）

⚠️ 这里 90% 新手会踩坑：

❌ File → Open → libelectron/             （DevEco 报 "Not a valid HarmonyOS project"）
✅ File → Open → libelectron/ohos_hap/   （正确）

打开后 Sync 依赖。首次 5-30 分钟，建议挂着干别的。

步骤 5：清除别人的本地证书 + 自动签名（3 分钟）

在这里插入图片描述

新版 libelectron 包默认带的是发布者本地证书路径，100% 用不了。

打开 ohos_hap/build-profile.json5，把 signingConfigs 清空：

- "signingConfigs": [
-   { "name": "default", "material": { "certpath": "/Users/zhanghao/.ohos/..." } }
- ]
+ "signingConfigs": []

然后 DevEco：

File → Project Structure → Signing Configs
  → 勾 "Automatically generate signature"
  → 登录华为账号
  → 几秒钟自动签好

步骤 6：放置你的应用代码（2 分钟）

新建 web-app/ 目录，放 4 个标准文件：

web-app/
  ├─ main.js          # 主进程（标准 Electron）
  ├─ preload.js       # contextBridge
  ├─ index.html       # 渲染层
  └─ package.json     # 只有 main 字段，不要 dependencies: electron

web-app/package.json 最小写法：

{
  "name": "your-app",
  "version": "1.0.0",
  "main": "main.js"
}

⚠️ 永远不要写：

"dependencies": {
  "electron": "37.x.x"    ← 错！会让运行时找不到模块
}

web-app/main.js 鸿蒙必需的三段配置：

const { app, BrowserWindow } = require('electron');
const path = require('path');

// 鸿蒙必备 #1：禁用 GPU（不禁会 1-3 秒白屏崩溃）
function isOhos() {
  return process.platform === 'ohos' || process.platform === 'openharmony' ||
         (process.resourcesPath && process.resourcesPath.includes('/data/storage/'));
}
if (isOhos()) {
  app.disableHardwareAcceleration();
  app.commandLine.appendSwitch('disable-gpu');
  app.commandLine.appendSwitch('disable-gpu-compositing');
  app.commandLine.appendSwitch('disable-software-rasterizer');
  app.commandLine.appendSwitch('use-gl', 'disabled');
}

// 鸿蒙必备 #2：BrowserWindow 用安全模式
function createWindow() {
  const win = new BrowserWindow({
    width: 1024, height: 720,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,    // 必开
      nodeIntegration: false,    // 必关
      sandbox: false              // 鸿蒙下 sandbox 兼容性不佳
    }
  });
  win.loadFile(path.join(__dirname, 'index.html'));
}

app.whenReady().then(createWindow);

// 鸿蒙必备 #3：全局错误捕获（不写就什么也调不出来）
process.on('uncaughtException', err => console.error('[main]', err));
process.on('unhandledRejection', r => console.error('[main]', r));

把 web-app/ 同步到 libelectron/ohos_hap/web_engine/src/main/resources/resfile/resources/app/——写个脚本省得每次手动复制：

#!/bin/bash
# scripts/sync-to-libelectron.sh
TARGET="./libelectron/ohos_hap/web_engine/src/main/resources/resfile/resources/app"
mkdir -p "$TARGET" && rm -rf "$TARGET"/*
cp -r ./web-app/* "$TARGET"/
echo "✅ synced"

步骤 7：连真机并 Run（5 分钟）

# 设备开发者模式：设置 → 关于本机 → 软件版本连点 7 次 → 输锁屏密码
# USB 调试：设置 → 开发者选项 → 打开"USB 调试"

# 接 USB 线，验证
hdc list targets   # 应该看到设备号

# 推荐改为无线调试（USB 一段时间会抽风）
hdc tmode port 5555
hdc tconn <设备IP>:5555

DevEco 右上角设备下拉框选刚连上的设备 → 点 ▶ Run。

首次部署 1-2 分钟。窗口出来 = 完整链路打通。

在这里插入图片描述

四、整套配完后的环境长什么样

写完这一晚，你本机的工具栈应该是这样：

~/dev/
  ├─ electron-playground/                    # 本机 Electron 实验场
  │   ├─ package.json (devDependencies: electron 37)
  │   └─ node_modules/
  │
  └─ my-ohos-electron-app/                   # 鸿蒙 Electron 工程
      ├─ web-app/                            # 你写的应用代码
      │   ├─ main.js
      │   ├─ preload.js
      │   ├─ index.html
      │   └─ package.json (只有 main 字段)
      │
      ├─ scripts/
      │   └─ sync-to-libelectron.sh          # 同步脚本
      │
      └─ libelectron/                        # 解压后的预编译包
          └─ ohos_hap/                       ← DevEco 打开这里
              ├─ AppScope/
              ├─ electron/                   # entry 模块
              ├─ web_engine/                 # HSP 模块
              │   └─ ...resfile/resources/app/  ← 同步的目标
              └─ build-profile.json5

在这里插入图片描述

工具版本：

DevEco Studio:    5.1.0.xxx
Node.js:          20.18.1
本机 Electron:    37.x（开发期辅助）
libelectron:      新版双模块 / Electron 37.2.0
鸿蒙 SDK:         API 17 / 20 / 23
设备:             HarmonyOS 6.x / API 23（推荐）

五、几个"看似奇怪但很重要"的细节

5.1 你写的 main.js 不是被 electron . 启动的

桌面 Electron 习惯：

electron .                              # 主进程进程名是 electron

鸿蒙 Electron：

EntryAbility（鸿蒙原生 Ability）
  → 加载 libelectron.so
  → libelectron 内部启动 Chromium + Node.js
  → 找到 resfile/resources/app/main.js
  → 执行它

意味着：

  • 你的 main.js 不是入口进程——鸿蒙 Ability 才是
  • 应用启动慢 = Ability 启动慢，跟 Node 启动无关
  • 想拿启动参数：process.argv 在鸿蒙下结构不太一样

5.2 package.json 里写依赖能装吗？

可以——但只有纯 JS 依赖能用：

{
  "main": "main.js",
  "dependencies": {
    "lodash": "^4.17.21",      ✅ 纯 JS，能用
    "axios": "^1.6.0",          ✅ 纯 JS，能用
    "marked": "^11.0.0",        ✅ 纯 JS，能用
    "electron-store": "^8.1.0", ⚠️ 纯 JS 但行为待验
    "sqlite3": "^5.1.6",        ❌ native binding，跑不了
    "keytar": "^7.9.0"          ❌ 鸿蒙没系统密钥链
  }
}

实际同步流程：

# 在 web-app/ 下
cd web-app
npm install --omit=dev          # 装 dependencies 但不装 devDependencies
# 此时 web-app/node_modules/ 出现

# 同步整个 web-app/（包括 node_modules）到 libelectron
./scripts/sync-to-libelectron.sh

node_modules 会被打到 HAP 包里。

5.3 调试方式：DevEco Console 几乎没用

90% 的真问题要靠 hdc。在 ~/.zshrc 里加几个别名：

# Electron 鸿蒙调试常用别名
alias hl='hdc shell hilog | grep -iE'
alias hlapp='hdc shell hilog | grep -iE "com.your.bundle|electron"'
alias hreboot='hdc shell reboot'
alias hcrash='hdc shell ls /data/log/faultlog/faultlogger/ | tail -5'

hlapp 那一行把 com.your.bundle 改成你的 bundleName——以后调试一个命令搞定。

5.4 DevTools 开不了

鸿蒙 Electron 上 win.webContents.openDevTools() 默认不工作。

替代方案：

// main.js 里开一个远程调试端口
app.commandLine.appendSwitch('remote-debugging-port', '9222');

// 本机用 Chrome 连
//   chrome://inspect → Configure → 加 192.168.x.x:9222
//   然后 inspect 选你的页面

但 hdc 端口转发要先做：

hdc fport tcp:9222 tcp:9222

六、一份"如果今晚我重装一遍"的最短清单

把上面整套浓缩成 1 张表：

# 步骤 命令 / 操作 耗时
1 鸿蒙基础环境 见上一篇 -
2 nvm 切到 Node 20.18.1 nvm use 20.18.1 1 min
3 本机装 Electron 37 npm install --save-dev electron@37 3 min
4 下 libelectron 新版双模块 官方仓库或社区下载 10-20 min
5 解压 unzip libelectron.zip 1 min
6 DevEco 打开 ohos_hap/ 子目录 File → Open 1 min
7 清空 signingConfigs + 自动签名 改 build-profile.json5 2 min
8 改 bundleName 改 AppScope/app.json5 1 min
9 写 web-app（main / preload / html / package.json） 用本文模板 5 min
10 同步到 resfile/resources/app sync 脚本 5 sec
11 设备开发者模式 + USB 调试 系统设置 2 min
12 hdc tmode + tconn 命令行 1 min
13 DevEco Run 点 ▶ 2 min

总计：30-45 分钟（不算 libelectron 下载）。

七、几个"装错了/做错了"的真实代价表

不是吓你，是让你知道哪步省一点时间会赔多少时间：

省的 赔的
跳过本机 Electron 安装 没 IDE 类型提示，写 API 全靠记
装 Node 22+ hvigor 报 crypto.hash is not a function，查半小时
用旧版 libelectron 跑 6.1 设备 napi_unwrap fail 闪退，只能换包（见 FAQ #09）
不改 bundleName 装不上去或覆盖别人的 Demo
不清空 signingConfigs 签名失败，查"为什么我密码错了"半小时
package.json 写 electron dep 运行时找不到模块，闪退
不禁 GPU 启动 1-3 秒后白屏 cppcrash（见 FAQ #10）
跳过 hdc 加 PATH 之后每次调试都要打全路径

八、写在最后

回到开头那个最常被问的问题——

“在鸿蒙 PC 上做 Electron，我要装什么？”

最朴素的答案是：

鸿蒙基础环境 + Node 20.18.1 + 本机 Electron 37 + libelectron 新版双模块。

剩下的都是细节。

但这里头最容易被忽视的事是：

鸿蒙 Electron 不是"把你的桌面 Electron 应用拷过来跑"，是"用你的应用代码 + libelectron 这个鸿蒙特化运行时"。

理解了这一点，下面这些坑你都不会再踩：

  • 为什么 npm install electron 之后还需要下 libelectron
  • 为什么 package.json 写了 electron 反而启动不了
  • 为什么 @electron/remote 鸿蒙不能用
  • 为什么 keytar / native-keymap / sqlite3 必须 mock

鸿蒙 Electron = 一个独特的 Electron 分发版本，不是 Electron 的子集，也不是 Electron 的超集——是个"鸿蒙特化版"。把它当独立平台对待，所有困惑就消失了。

附录 A：本文涉及的所有命令（可复制）

# ===== 本机环境 =====
nvm use 20.18.1
mkdir ~/dev/electron-playground && cd $_
npm init -y
npm install --save-dev electron@37
npx electron --version

# ===== 设备 / hdc =====
hdc shell param get const.product.software.version
hdc list targets
hdc tmode port 5555
hdc tconn <设备IP>:5555

# ===== libelectron 工程改造 =====
unzip libelectron.zip
# 编辑 ohos_hap/build-profile.json5 → signingConfigs: []
# 编辑 ohos_hap/AppScope/app.json5 → bundleName: "com.demo.xxx"
# 编辑 ohos_hap/AppScope/.../string.json → app_name: "..."

# ===== 同步应用代码 =====
TARGET="./libelectron/ohos_hap/web_engine/src/main/resources/resfile/resources/app"
mkdir -p "$TARGET" && rm -rf "$TARGET"/*
cp -r ./web-app/* "$TARGET"/

# ===== 调试 =====
hdc shell hilog | grep -iE "com.demo.xxx|electron|cppcrash|napi_"
hdc shell aa start -a EntryAbility -b com.demo.xxx
hdc shell bm uninstall -n com.demo.xxx
hdc file recv /data/log/faultlog/faultlogger/cppcrash-*.log ./crash.log
hdc fport tcp:9222 tcp:9222   # DevTools 远程调试

附录 B：常见"装/不装"问题速查

问 答
我能用 yarn / pnpm 代替 npm 吗？ 本机可以，但 web-app 同步前建议用 npm 装 dep（兼容性最好）
一定要装 nvm 吗？ 强烈推荐——hvigor 对 Node 版本很敏感
本机 Electron 版本要跟 libelectron 完全一致吗？ 大版本对齐就行（37.x.0 / 37.x.5 差异不大）
Node 22 真的不能用吗？ 现阶段确实会撞兼容，等鸿蒙工具链官方说支持再升
TypeScript 能用吗？ 能。但要在 web-app 里自己跑 tsc → js，不要把 .ts 直接塞进去
Vue / React 能用吗？ 能。前端 build 完产物（dist/ 或 build/）放进 web-app 即可
需要装 Python 吗？ 不需要（除非你的应用本身要 spawn Python）
需要装 Docker 吗？ 不需要
# electron # harmonyos # javascript
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

OpenHarmony动态权限申请与隐私合规实践

在 OpenHarmony 应用开发中，相机、麦克风、定位、文件读写、相册等敏感系统资源，不支持静态直接授权，必须在运行时动态向用户申请。Android、iOS、鸿蒙均遵循「隐私最小权限原则」，而 OpenHarmony 的权限体系更严谨、分层更清晰，分为普通权限、用户授权权限、系统特权权限三类。很多开发者常见问题：权限已配置却无效、首次拒绝后无法再次弹窗、永久拒绝无引导、多权限批量申请混乱、缺少

avatar 人工智能6S服务平台
cover

基于 HarmonyOS API 24 的「孔雀东南飞」古诗阅读应用开发实战

avatar 人工智能6S服务平台
cover

【共创季稿事节】鸿蒙原生ArkTS动态列表布局实战_State_ForEach完整指南

avatar 人工智能6S服务平台