Electron for HarmonyOS 开发环境搭建

@VON

发布于 2025-12-21 12:29:52

580

一、环境准备

（基于 DevEco Studio + Compatible SDK 5.0.5 + Electron 34）

1. 系统与硬件要求

操作系统：Windows 10/11、macOS 10.15+、Ubuntu 22.04+
IDE：DevEco Studio 5.0+（需匹配 Compatible SDK 5.0.5）
Node.js：v18.x 或更高版本（建议 v20.18.1）
硬件：≥8GB 内存（推荐 16GB）、≥20GB 可用存储空间
目标设备：HarmonyOS NEXT（API 20+）平板/PC 设备

2. 工具下载

DevEco Studio：从华为开发者官网下载 5.0+ 版本，安装时勾选 HarmonyOS SDK（包含 Compatible SDK 5.0.5）。
Electron for HarmonyOS 预编译包：
- 访问 Electron 鸿蒙仓库，下载最新 Release 包（如 v34.6.0-20251105.1-release.zip）。
Node.js：从 Node.js 官网安装 v20.18.1（建议通过 nvm 管理版本）。

二、DevEco Studio 配置

1. 项目结构初始化

打开 DevEco Studio，选择 File → Open，导入解压后的 Electron 预编译包根目录（通常命名为 ohos_hap）。

2. 进入 File → Project Structure（如截图所示），配置项目基础信息：

Bundle name：填写唯一包名（如 com.huawei.ohos_electron）。
Compatible SDK：选择 5.0.5(17)（需与设备系统版本匹配）。

切换到 Signing Configs 标签，点击 Auto-generate signature 生成调试签名（首次运行必需）。

2. 依赖配置

这里保持默认即可

三、Electron 项目集成

1. 放置 Electron 应用代码

将你的 Electron 应用代码（或示例代码）放入以下目录：

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

示例 Electron 项目结构：

app/
├── main.js       # 主进程入口
├── package.json  # 项目配置
├── index.html    # 渲染进程页面
└── renderer.js   # 渲染进程逻辑

2. 基础示例代码

可使用以下示例：

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>

四、运行与调试

1. 设备连接

在鸿蒙设备上启用 开发者模式 和 USB 调试（设置 → 关于设备 → 连续点击版本号 7 次）。
使用 USB Type-C 连接设备与电脑，在 DevEco Studio 顶部工具栏确认设备已识别。

2. 编译运行

点击 DevEco Studio 右上角的 Run 按钮（或按 Shift+F10）。
首次编译需等待 5-10 分钟，编译完成后应用会自动安装到设备并启动。

编译成功

3. 调试技巧

日志查看：在 DevEco Studio 的 Log 面板中，过滤关键词 Electron 查看应用日志。
DevTools 调试：在 main.js 中添加 win.webContents.openDevTools()，启动后自动打开 Chrome DevTools。

五、常见问题解决

“SysCap 不匹配”报错：
- 检查 module.json5 中的 reqSysCapabilities，移除 SystemCapability.Test.PerfTest 等测试类能力。
“找不到 .so 文件”报错：
- 确认 libs/arm64-v8a 目录包含 libelectron.so、libadapter.so 等核心库。
Electron 窗口不显示：
- 在 main.js 中添加 app.disableHardwareAcceleration() 禁用硬件加速。