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.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 打开项目
  1. 启动 DevEco Studio
  2. 选择 File → Open
  3. 打开 ohos_hap 项目目录
4.2 配置签名

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

  1. 进入 File → Project Structure → Signing Configs
  2. 自动生成调试签名或配置发布签名
4.3 连接设备
  1. 使用 USB Type-C 数据线连接开发电脑和鸿蒙设备
  2. 在设备上启用开发者模式和 USB 调试
  3. 在 DevEco Studio 中确认设备已连接（顶部工具栏会显示设备名称）
4.4 编译和运行
  1. 点击右上角的 ▶️ Run 按钮（或按 Shift + F10）
  2. 系统会自动进行以下操作：
    • 编译 HAP 包
    • 重新签名
    • 安装到设备
    • 启动应用

运行应用

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

步骤 5: 验证运行效果

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

运行效果

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

🔍 常见问题与故障排查

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

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

解决方案:

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

Q2: 应用启动后白屏

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

解决方案:

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

Q3: 设备无法识别

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

解决方案:

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

Q4: 签名失败

原因: 签名配置不正确

解决方案:

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

Q5: 应用运行缓慢或卡顿

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

解决方案:

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

📚 进阶开发指南

调用鸿蒙原生能力

通过适配器可以调用鸿蒙系统的原生 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

性能优化建议

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

🎯 最佳实践

1. 目录结构规范

保持清晰的项目结构：

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

2. 安全性考虑

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

3. 跨平台兼容性

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

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

🔗 相关资源

官方文档

开源项目

学习资源

社区支持

📝 总结

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

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

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

🌟 贡献指南

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

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

最后更新: 2025年11月

维护者: @jianguoxu

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

# electron # harmonyos # javascript
Logo
人工智能6S服务平台

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

更多推荐

鸿蒙系统app开发：运动监测app（五）

State装饰器实现UI与数据的双向绑定username和password实时响应用户输入isLoading控制异步操作期间的UI状态rememberMe保存用户偏好设置。

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

基于小智ESP32S3的智能控制小车

avatar 人工智能6S服务平台

如何在CANN 7.0框架下，利用Ascend C快速开发自定义AI算子

2025年昇腾CANN训练营第二季现已正式启动！本季训练营基于CANN开源开放全场景，精心设计了四大定制化专题课程：0基础入门系列、码力全开特辑、开发者案例等，旨在助力不同阶段的开发者快速提升Ascend C算子开发技能。完成Ascend C算子中级认证，即可领取精美证书；积极参与社区任务，更有机会赢取华为手机、平板、开发板等丰厚大奖！🔥立即报名2025年昇腾CANN训练营第二季报名链接本文深入

avatar 人工智能6S服务平台