一、前言：为什么要做鸿蒙 + Electron 开发？

随着鸿蒙（HarmonyOS）生态的快速发展，越来越多开发者希望将已有的 Electron 跨端应用适配到鸿蒙系统，或基于 Electron 开发同时支持 Windows/macOS/ 鸿蒙的跨端应用。Electron 凭借 “HTML+CSS+JavaScript” 的技术栈优势，降低了桌面应用开发门槛；而鸿蒙系统的分布式能力，能让应用具备更强的设备联动性。

本文将从环境搭建、核心原理、实战开发三个维度，带你快速掌握鸿蒙系统下 Electron 应用的开发与适配，全程附带可运行的代码案例和实操截图，零基础也能上手。

二、前置知识与环境准备

2.1 核心概念说明

  • Electron：基于 Chromium 和 Node.js 的跨端框架，允许使用前端技术开发桌面应用，可打包为 Windows/macOS/Linux 应用。
  • 鸿蒙对 Electron 的支持：鸿蒙系统（OpenHarmony 4.0+）通过兼容层支持 Electron 应用运行，同时提供了鸿蒙特有的 API 扩展，让 Electron 应用能调用鸿蒙的分布式能力。
  • 开发核心：基于标准 Electron 开发流程，增加鸿蒙适配层代码，最终打包为鸿蒙可运行的 APP。

2.2 环境搭建（图文步骤）

所需工具
  1. Node.js（v16+，Electron 依赖）
  2. DevEco Studio（鸿蒙开发工具，用于鸿蒙侧调试）
  3. Electron Forge（Electron 打包工具）
  4. 鸿蒙模拟器 / 真机（OpenHarmony 4.0+）
环境搭建步骤

步骤 1：安装 Node.js 与 Electron 基础环境下载 Node.js（https://nodejs.org/）并安装，验证安装成功：

bash

运行

# 打开终端执行
node -v # 输出v16.20.0+即可
npm -v # 输出8.19.4+即可

# 全局安装Electron Forge（打包工具）
npm install -g @electron-forge/cli

图 1：终端验证 Node.js 安装成功（图片描述：终端中执行 node -v 和 npm -v，分别显示版本号，无报错）

步骤 2：安装 DevEco Studio 并配置鸿蒙环境

  1. 下载 DevEco Studio（https://developer.huawei.com/consumer/cn/deveco-studio/）；
  2. 安装完成后，在 Settings 中配置鸿蒙 SDK（选择 4.0 + 版本）；
  3. 创建鸿蒙模拟器（Phone 设备，API Version 9）。

图 2：DevEco Studio 配置鸿蒙 SDK（图片描述：DevEco Studio 的 Settings 界面，SDK Location 中显示鸿蒙 4.0 SDK 路径，已勾选相关组件）

步骤 3：验证 Electron 与鸿蒙环境连通性

bash

运行

# 创建空文件夹，初始化Electron项目
mkdir electron-harmony-demo
cd electron-harmony-demo
npm init electron-app@latest . -- --template=webpack

执行完成后，目录结构如下：图 3：Electron 项目初始化后的目录结构（图片描述：VS Code 中显示的项目目录，包含 src、package.json、node_modules 等文件夹 / 文件）

三、实战开发：鸿蒙 + Electron 简易跨端应用

3.1 功能需求

开发一个简单的跨端应用，实现：

  1. 基础界面展示（包含鸿蒙系统标识）；
  2. 调用鸿蒙系统的设备信息 API（扩展能力）；
  3. 同时支持 Windows 和鸿蒙系统运行。

3.2 核心代码开发

步骤 1：修改主进程代码（src/main.js）

主进程是 Electron 的核心，负责窗口创建、系统 API 调用，这里增加鸿蒙适配逻辑：

javascript

运行

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

// 判断当前运行环境是否为鸿蒙系统
function isHarmonyOS() {
  // 鸿蒙系统的process.platform返回'harmony'（OpenHarmony 4.0+）
  return process.platform === 'harmony';
}

// 创建窗口函数
function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      // 鸿蒙环境下开启节点集成
      nodeIntegration: isHarmonyOS(),
      contextIsolation: !isHarmonyOS()
    }
  });

  // 加载本地页面
  mainWindow.loadFile(path.join(__dirname, 'index.html'));

  // 鸿蒙环境下打开调试工具（方便调试）
  if (isHarmonyOS()) {
    mainWindow.webContents.openDevTools();
  }
}

// 监听渲染进程的设备信息请求
ipcMain.handle('get-device-info', async () => {
  if (isHarmonyOS()) {
    // 鸿蒙系统下调用鸿蒙设备信息API
    // 注：需提前安装鸿蒙Electron扩展包
    const harmonyApi = require('@ohos/electron-extension');
    return {
      system: 'HarmonyOS',
      version: harmonyApi.system.getVersion(),
      deviceId: harmonyApi.device.getId()
    };
  } else {
    // 其他系统返回基础信息
    return {
      system: process.platform,
      version: process.version,
      deviceId: '非鸿蒙环境暂不支持'
    };
  }
});

// 应用就绪后创建窗口
app.whenReady().then(() => {
  createWindow();
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

// 关闭所有窗口时退出应用（macOS除外）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit();
});
步骤 2：修改预加载脚本（src/preload.js）

预加载脚本用于主进程与渲染进程通信，暴露安全的 API 给前端：

javascript

运行

const { contextBridge, ipcRenderer } = require('electron');

// 向渲染进程暴露API
contextBridge.exposeInMainWorld('electronApi', {
  getDeviceInfo: () => ipcRenderer.invoke('get-device-info'),
  isHarmony: () => ipcRenderer.invoke('is-harmony-os')
});
步骤 3：编写前端页面（src/index.html）

实现基础界面，调用预加载脚本暴露的 API：

html

预览

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>鸿蒙+Electron Demo</title>
  <style>
    body {
      margin: 0;
      padding: 20px;
      font-family: Arial, sans-serif;
      background-color: #f5f5f5;
      text-align: center;
    }
    .container {
      margin-top: 50px;
    }
    .logo {
      width: 100px;
      height: 100px;
      margin: 0 auto;
    }
    .device-info {
      margin-top: 30px;
      padding: 20px;
      background: white;
      border-radius: 8px;
      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
      max-width: 500px;
      margin-left: auto;
      margin-right: auto;
    }
    button {
      padding: 10px 20px;
      background: #007dff;
      color: white;
      border: none;
      border-radius: 4px;
      cursor: pointer;
      font-size: 16px;
      margin-top: 20px;
    }
    button:hover {
      background: #0058c9;
    }
  </style>
</head>
<body>
  <div class="container">
    <!-- 鸿蒙logo（可替换为实际图片） -->
    <img src="https://developer.huawei.com/consumer/cn/images/logo-harmonyos.png" class="logo" alt="HarmonyOS Logo">
    <h1>鸿蒙+Electron 跨端应用</h1>
    <button onclick="getDeviceInfo()">获取设备信息</button>
    <div class="device-info" id="deviceInfo">
      点击按钮获取设备信息...
    </div>
  </div>

  <script>
    // 调用Electron暴露的API获取设备信息
    async function getDeviceInfo() {
      try {
        const info = await window.electronApi.getDeviceInfo();
        const infoElement = document.getElementById('deviceInfo');
        infoElement.innerHTML = `
          <p>系统类型：${info.system}</p>
          <p>系统版本：${info.version}</p>
          <p>设备ID：${info.deviceId}</p>
        `;
      } catch (error) {
        document.getElementById('deviceInfo').innerHTML = `获取失败：${error.message}`;
      }
    }
  </script>
</body>
</html>
步骤 4：修改 package.json（添加鸿蒙适配配置）

在 package.json 中添加鸿蒙打包相关配置：

json

{
  "name": "electron-harmony-demo",
  "version": "1.0.0",
  "description": "鸿蒙+Electron跨端应用示例",
  "main": "src/main.js",
  "scripts": {
    "start": "electron-forge start",
    "package": "electron-forge package",
    "make": "electron-forge make",
    "package:harmony": "electron-forge package --platform=harmony --arch=arm64"
  },
  "devDependencies": {
    "@electron-forge/cli": "^7.2.0",
    "@electron-forge/maker-deb": "^7.2.0",
    "@electron-forge/maker-rpm": "^7.2.0",
    "@electron-forge/maker-squirrel": "^7.2.0",
    "@electron-forge/maker-zip": "^7.2.0",
    "electron": "^27.0.0"
  },
  "dependencies": {
    "@ohos/electron-extension": "^1.0.0",
    "electron-squirrel-startup": "^1.0.0"
  }
}

3.3 运行与打包（图文演示）

步骤 1：本地运行（Windows/macOS）

bash

运行

# 安装依赖
npm install

# 启动应用
npm start

图 4：Windows 下运行的 Electron 应用界面（图片描述：应用窗口显示鸿蒙 logo、标题，点击 “获取设备信息” 后显示系统类型为 win32，版本等信息）

步骤 2：鸿蒙系统打包与运行

bash

运行

# 安装鸿蒙Electron扩展包
npm install @ohos/electron-extension --save

# 打包鸿蒙应用
npm run package:harmony

打包完成后，会在 out 目录生成鸿蒙可运行的 APP 包，将其导入 DevEco Studio，部署到鸿蒙模拟器 / 真机：

图 5：鸿蒙模拟器中运行的应用界面（图片描述：鸿蒙模拟器中显示应用界面，点击按钮后显示系统类型为 HarmonyOS，设备 ID 等鸿蒙特有的信息）

四、核心知识点解析

4.1 鸿蒙环境判断

Electron 在鸿蒙系统下process.platform返回harmony，这是判断运行环境的核心依据，也是适配逻辑的关键。

4.2 鸿蒙 API 调用

通过@ohos/electron-extension扩展包，Electron 应用可调用鸿蒙系统的原生 API，如设备信息、分布式数据管理、设备联动等，实现鸿蒙特有的功能。

4.3 跨端适配注意事项

  1. 鸿蒙系统主要为 ARM 架构，打包时需指定--arch=arm64；
  2. 鸿蒙环境下 Electron 的contextIsolation需关闭，否则无法调用 Node.js API；
  3. 鸿蒙的权限管理更严格，调用设备信息、文件等 API 需在鸿蒙应用配置中声明权限。

五、常见问题与解决方案

问题现象 原因 解决方案
鸿蒙模拟器中应用启动闪退 架构不匹配 打包时指定 --arch=arm64
调用鸿蒙 API 提示 “模块未找到” 未安装扩展包 执行 npm install @ohos/electron-extension
前端无法调用 electronApi 预加载脚本配置错误 检查 contextBridge 暴露 API 的语法，确保 contextIsolation 配置正确

六、总结

本文通过一个完整的实战案例，讲解了鸿蒙 + Electron 跨端应用的开发流程，核心要点如下：

  1. 鸿蒙系统（OpenHarmony 4.0+）已原生支持 Electron 应用，通过扩展包可调用鸿蒙特有 API；
  2. 开发核心是 “标准 Electron 开发 + 鸿蒙环境适配”，无需重构已有 Electron 代码；
  3. 打包时需注意鸿蒙的架构和权限配置，确保应用能正常运行。

鸿蒙 + Electron 的组合，既保留了 Electron 前端开发的便捷性，又能利用鸿蒙的分布式能力，是跨端应用开发的优质选择

# harmonyos # electron # 华为 # 鸿蒙
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙应用开发UI基础第十六节：图片展示组件Image核心讲解与实战（基础篇）

avatar HarmonyOS开发者社区
cover

鸿蒙生态崛起：深度解析鸿蒙开发工程师的机遇、挑战与核心技能

avatar HarmonyOS开发者社区
cover

鸿蒙应用开发工程师职位深度解析与面试指南

avatar HarmonyOS开发者社区