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

徐建国

发布于 2025-11-29 15:08:33

1210

Electron HarmonyOS 开发环境搭建完整指南

📖 前言

Electron 是一个使用 JavaScript、HTML 和 CSS 构建跨平台桌面应用程序的开源框架。通过将 Chromium 渲染引擎和 Node.js 运行时嵌入到二进制文件中，Electron 允许开发者使用统一的 Web 技术栈，创建可在 Windows、macOS、Linux 和 HarmonyOS 上运行的原生桌面应用。

Electron 架构优势

🎯 跨平台: 一套代码，多端运行
🚀 Web 技术栈: 使用熟悉的前端技术开发桌面应用
📦 丰富生态: npm 生态系统中数十万个包可直接使用
🔧 原生能力: 可访问系统底层 API 和硬件资源

🔧 系统要求

开发环境要求

操作系统: Windows 10/11、macOS 10.15+、Ubuntu 22.04+
IDE: DevEco Studio 5.0+ （鸿蒙官方 IDE）
Node.js: 建议 v18.x 或更高版本
内存: 至少 8GB RAM（推荐 16GB）
存储空间: 至少 20GB 可用空间

目标设备要求

鸿蒙设备: HarmonyOS NEXT (API 20)
设备类型: 平板电脑或 2in1 设备
连接方式: USB Type-C 数据线

⚠️ 重要提示: 如果需要从源码编译 Electron，必须使用 Ubuntu 22.04 环境。但对于大多数开发场景，直接使用预编译产物即可。

🚀 快速开始

步骤 1: 获取 Electron 编译产物

1.1 访问官方仓库

使用华为账号登录 Electron HarmonyOS 仓库[1]。

1.2 下载 Release 包

选择 Electron 34 版本（推荐使用最新稳定版）
下载最新日期的编译产物
文件通常为 .zip 格式，大小约 200-300MB

下载 Electron Release 包

💡 提示: 建议下载最新日期的版本以获得最新的 bug 修复和功能更新。

步骤 2: 解压编译产物到项目目录

2.1 解压文件结构

将下载的压缩包逐层解压到项目目录，最终文件结构应如下：

ohos_hap/
├── electron/
│   ├── libs/                 # 原生库文件
│   │   ├── libelectron.so   # Electron 核心引擎
│   │   ├── libadapter.so    # 鸿蒙适配层
│   │   ├── libffmpeg.so     # 多媒体支持
│   │   └── libc++_shared.so
│   └── src/
└── web_engine/              # Web 引擎适配模块

2.2 确认关键文件

确保以下关键库文件存在于 electron/libs/arm64-v8a/ 目录：

✅ libelectron.so (约 150-200MB)
✅ libadapter.so (约 5-10MB)
✅ libffmpeg.so (约 10-20MB)
✅ libc++_shared.so (约 1-2MB)

项目目录结构

步骤 3: 放置 Electron 应用代码

3.1 应用代码目录

将你的 Electron 应用代码（或编译产物）放置到以下目录：

web_engine/src/main/resources/resfile/resources/app/

3.2 标准 Electron 应用结构

典型的 Electron 应用应包含以下文件：

app/
├── main.js           # 主进程入口文件（必需）
├── package.json      # 项目配置文件（必需）
├── index.html        # 渲染进程页面
├── renderer.js       # 渲染进程逻辑
└── node_modules/     # 依赖包（如果有）

3.3 基础示例代码

如果你还没有 Electron 应用，可以使用以下简单示例：

main.js (主进程):

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

function createWindow() {
const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false
    }
  });

  win.loadFile('index.html');
}

app.whenReady().then(createWindow);

app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
    app.quit();
  }
});

package.json:

{
  "name": "electron-harmonyos-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron ."
  }
}

index.html:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Hello HarmonyOS!</title>
</head>
<body>
  <h1>欢迎使用 Electron on HarmonyOS!</h1>
  <p>这是运行在鸿蒙系统上的 Electron 应用</p>
</body>
</html>

应用代码放置位置

步骤 4: 使用 DevEco Studio 运行项目

4.1 打开项目

启动 DevEco Studio
选择 File → Open
打开 ohos_hap 项目目录

4.2 配置签名

如果是首次运行，需要配置应用签名：

进入 File → Project Structure → Signing Configs
自动生成调试签名或配置发布签名

4.3 连接设备

使用 USB Type-C 数据线连接开发电脑和鸿蒙设备
在设备上启用开发者模式和 USB 调试
在 DevEco Studio 中确认设备已连接（顶部工具栏会显示设备名称）

4.4 编译和运行

点击右上角的 ▶️ Run 按钮（或按 Shift + F10）
系统会自动进行以下操作：
- 编译 HAP 包
- 重新签名
- 安装到设备
- 启动应用

运行应用

⏱ 提示: 首次编译可能需要 5-10 分钟，请耐心等待。

步骤 5: 验证运行效果

应用成功启动后，你应该能在鸿蒙设备上看到 Electron 应用界面。

运行效果

验证检查项

✅ 应用窗口正常显示
✅ 可以进行交互操作
✅ 控制台无错误信息
✅ 主进程和渲染进程通信正常

🔍 常见问题与故障排查

Q1: 编译失败，提示找不到 libelectron.so

原因: 原生库文件未正确放置

解决方案:

检查 electron/libs/arm64-v8a/ 目录是否包含所有 .so 文件
确保文件权限正确（可执行权限）
重新解压编译产物

Q2: 应用启动后白屏

原因: Electron 应用代码路径不正确或 main.js 有错误

解决方案:

确认应用代码在正确的 resources/app/ 目录下
检查 main.js 中的路径是否正确
查看 DevEco Studio 的 Log 输出定位错误

Q3: 设备无法识别

原因: USB 调试未开启或驱动未安装

解决方案:

在鸿蒙设备上进入 设置 → 系统 → 开发者选项
开启 USB 调试
Windows 用户需安装鸿蒙设备驱动

Q4: 签名失败

原因: 签名配置不正确

解决方案:

使用自动生成的调试签名
确保 build-profile.json5 中的签名配置正确
清理项目后重新编译 (Build → Clean Project)

Q5: 应用运行缓慢或卡顿

原因: 资源占用过高或设备性能不足

解决方案:

优化 Electron 应用代码，减少资源占用
使用 chrome://inspect 进行性能分析
确保设备有足够的可用内存

📚 进阶开发指南

调用鸿蒙原生能力

通过适配器可以调用鸿蒙系统的原生 API，例如：

// 在 ArkTS 中定义适配器
export class CustomAdapter extends BaseAdapter {
  callNativeFunction() {
    // 调用鸿蒙原生 API
  }
}

// 在 Electron 中通过 IPC 调用
ipcRenderer.invoke('native-call').then(result => {
  console.log(result);
});

使用 Node.js Addon

如果需要使用 Node.js 原生模块（如 sqlite3），请参考项目 docs/ 目录下的相关文档：

鸿蒙平台Electron加载addon（基于node-sqlite3-5.1.7）.pdf

性能优化建议

减少主进程负载: 将计算密集型任务移到渲染进程或 Worker
使用懒加载: 按需加载页面和资源
优化资源大小: 压缩图片、精简依赖包
启用缓存: 合理使用本地存储和缓存机制

🎯 最佳实践

1. 目录结构规范

保持清晰的项目结构：

your-electron-app/
├── main/           # 主进程代码
├── renderer/       # 渲染进程代码
├── preload/        # 预加载脚本
├── assets/         # 静态资源
└── utils/          # 工具函数

2. 安全性考虑

✅ 启用 contextIsolation
✅ 禁用 nodeIntegration（除非必要）
✅ 使用 preload 脚本暴露受控 API
✅ 验证和清理用户输入

3. 跨平台兼容性

虽然代码可以跨平台运行，但仍需注意：

文件路径使用 path.join() 而非硬编码
测试不同平台的特定功能
处理平台差异（如菜单、托盘图标）

🔗 相关资源

官方文档

📘 Electron 官方文档[2] - Electron 完整 API 文档和教程
🔧 DevEco Studio 文档[3] - 鸿蒙开发工具使用指南
🌟 HarmonyOS 开发者中心[4] - 鸿蒙官方开发资源

开源项目

🚀 鸿蒙版 Electron[5] - OpenHarmony SIG Electron 项目
💻 本项目代码仓库[6] - 完整的示例项目和技术博客
📦 Electron 示例应用[7] - Electron 官方快速开始模板

学习资源

📖 Electron 中文教程[8] - 从零开始学习 Electron
🎓 鸿蒙 ArkTS 语法[9] - ArkTS 编程语言入门
🛠️ Node.js Addon 开发[10] - 原生模块开发指南

社区支持

💬 Electron Discord 社区[11]
🐛 问题反馈[12] - 提交 Bug 或功能请求
📧 技术交流群：欢迎通过仓库联系方式加入

📝 总结

通过本指南，你已经学会了如何：

✅ 配置 Electron HarmonyOS 开发环境
✅ 获取和部署 Electron 编译产物
✅ 创建和运行 Electron 应用
✅ 处理常见问题和优化应用性能
✅ 调用鸿蒙原生能力

现在你可以开始构建自己的跨平台 Electron 应用了！如果遇到问题，请参考上述资源或在社区寻求帮助。

🌟 贡献指南

欢迎为本项目贡献代码和文档！

Fork 本仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

最后更新: 2025 年 11 月

维护者: @jianguoxu[13]

💡 温馨提示: 如果本指南对你有帮助，欢迎 Star ⭐ 本项目仓库！

参考资料

[1]

Electron HarmonyOS 仓库: https://devcloud.cn-north-4.huaweicloud.com/codehub/project/b19f5ea8ffd4492ea8c06ca2ebf3f858/codehub/2821214/home?ref=electron34-release

[2]

Electron 官方文档: https://www.electronjs.org/zh/docs/latest/

[3]

DevEco Studio 文档: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-tools-overview

[4]

HarmonyOS 开发者中心: https://developer.huawei.com/consumer/cn/harmonyos/

[5]

鸿蒙版 Electron: https://gitcode.com/openharmony-sig/electron

[6]

本项目代码仓库: https://gitcode.com/jianguoxu/electrondemo

[7]

Electron 示例应用: https://github.com/electron/electron-quick-start

[8]

Electron 中文教程: https://www.electronjs.org/zh/docs/latest/tutorial/quick-start

[9]

鸿蒙 ArkTS 语法: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guide

[10]

Node.js Addon 开发: https://nodejs.org/api/addons.html

[11]

Electron Discord 社区: https://discord.gg/electron

[12]

问题反馈: https://gitcode.com/jianguoxu/electrondemo/issues

[13]

@jianguoxu: https://gitcode.com/jianguoxu

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-11-08，如有侵权请联系 cloudcommunity@tencent.com 删除

进程

本文分享自大前端之旅微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度