鸿蒙 Electron 开发全攻略:从环境搭建到跨端应用实战
前言
随着鸿蒙 OS(HarmonyOS)生态的持续扩张,其 “一次开发、多端部署” 的核心优势已吸引大量开发者入局。而 Electron 作为成熟的跨端开发框架,凭借 “HTML+CSS+JavaScript” 的技术栈门槛低、生态丰富的特点,成为前端开发者快速构建桌面应用的首选。那么,如何将 Electron 与鸿蒙 OS 结合,让前端开发者无需学习鸿蒙原生开发语言,就能快速开发适配鸿蒙系统的跨端应用?
本文将从核心原理、环境搭建、实战开发、调试部署四个维度,带大家手把手实现一个鸿蒙 Electron 应用,全程配套可直接运行的代码案例与详细注释,无论是鸿蒙生态新手还是 Electron 老玩家,都能快速上手!
一、核心认知:鸿蒙与 Electron 的结合逻辑
在开始开发前,我们需要先明确一个关键问题:Electron 应用为何能在鸿蒙 OS 上运行?
1. 底层兼容原理
鸿蒙 OS 3.0 及以上版本支持 “Linux 容器” 与 “兼容层技术”,而 Electron 本质是基于 Chromium 内核 + Node.js 的桌面应用运行时,其 Linux 版本可通过鸿蒙的 Linux 兼容层直接运行。简单来说:
- 鸿蒙 OS 提供了 Linux 环境兼容能力,Electron Linux 版可无缝适配
- 开发者无需修改 Electron 核心代码,仅需针对鸿蒙系统做少量适配(如窗口样式、系统 API 调用)
2. 核心优势
- 技术栈复用:前端开发者可直接使用 HTML/CSS/JS/Vue/React 等现有技术栈,无需学习 ArkTS
- 跨端能力叠加:Electron 本身支持 Windows/macOS/Linux,结合鸿蒙后可实现 “一次开发,覆盖桌面 + 鸿蒙设备”
- 生态复用:Electron 丰富的 npm 包生态(如 UI 库、工具库)可直接引入鸿蒙应用
3. 适用场景
- 快速迁移现有 Electron 应用到鸿蒙 OS
- 开发轻量级鸿蒙桌面应用(如工具类、管理系统、文档阅读器)
- 前端团队快速切入鸿蒙生态,降低转型成本
二、环境搭建:零踩坑配置指南
1. 前置条件
| 环境 / 工具 | 版本要求 | 作用 |
|---|---|---|
| 鸿蒙 OS | 3.0 及以上(手机 / 平板 / 智慧屏 / PC) | 应用运行目标设备 |
| 开发机系统 | Windows 10/11 或 macOS 12+ | 编写与打包 Electron 应用 |
| Node.js | 16.x LTS 或 18.x LTS | Electron 运行依赖 |
| npm/yarn | 对应 Node.js 版本自带 | 包管理工具 |
| DevEco Studio | 4.0 及以上 | 鸿蒙应用调试与签名(可选) |
| VS Code | 任意稳定版 | 编写 Electron 代码(推荐) |
2. 环境搭建步骤
(1)安装 Node.js 与 Electron
-
第一步:下载 Node.js 16.x LTS 版本(官网链接),安装时勾选 “Add to PATH”,安装完成后在终端验证:
bash
运行
node -v # 输出 v16.20.2 表示成功 npm -v # 输出 8.19.4 左右版本 -
第二步:全局安装 Electron 脚手架工具,选择稳定版确保兼容性:
bash
运行
npm install -g electron@22.3.2 npm install -g electron-packager # 用于打包应用验证安装:
bash
运行
electron -v # 输出 v22.3.2 表示成功
(2)鸿蒙设备开启开发者模式
- 第一步:打开鸿蒙设备(以鸿蒙 PC 为例),进入「设置」→「系统和更新」→「开发者选项」
- 第二步:连续点击「版本号」7 次,激活开发者模式
- 第三步:开启「USB 调试」「允许安装未知来源应用」「Linux 环境兼容」(部分设备需在「开发人员选项」中手动开启,不同设备路径略有差异,可参考鸿蒙官方文档)
(3)DevEco Studio 配置(可选,用于鸿蒙 API 调试)
- 下载 DevEco Studio 4.0(官网链接),安装时勾选 “鸿蒙 SDK”
- 打开 DevEco Studio,进入「File」→「Settings」→「HarmonyOS SDK」,下载对应设备的 SDK 版本(如 HarmonyOS 3.1)
- 连接鸿蒙设备,在 DevEco Studio 中通过设备管理面板识别设备(确保 USB 调试已开启)
三、实战开发:从零构建鸿蒙 Electron 应用
本节将开发一个 “鸿蒙设备系统信息查看工具”,功能包括:显示设备型号、系统版本、CPU / 内存占用,配套完整代码与详细注释,可直接复制运行。
1. 项目初始化
(1)创建项目目录并初始化
bash
运行
mkdir harmony-electron-demo # 创建项目文件夹
cd harmony-electron-demo # 进入目录
npm init -y # 初始化package.json
(2)安装依赖包
bash
运行
# 核心依赖:electron、系统信息查询库
npm install electron@22.3.2 systeminformation --save
# 开发依赖:nodemon(热重载,提升开发效率)
npm install nodemon --save-dev
(3)修改 package.json 配置
json
{
"name": "harmony-electron-demo",
"version": "1.0.0",
"main": "main.js", // 应用入口文件
"scripts": {
"start": "nodemon --exec electron .", // 热重载启动命令
"package": "electron-packager . harmony-system-tool --platform=linux --arch=x64 --out=dist" // 打包Linux版本(适配鸿蒙)
},
"devDependencies": {
"nodemon": "^3.1.0"
},
"dependencies": {
"electron": "^22.3.2",
"systeminformation": "^5.22.10"
}
}
2. 核心代码实现
(1)主进程文件:main.js(Electron 核心配置)
javascript
运行
const { app, BrowserWindow, ipcMain } = require('electron');
const si = require('systeminformation'); // 系统信息查询库
const path = require('path');
// 全局变量存储窗口实例,避免被垃圾回收
let mainWindow;
// 创建应用窗口函数
function createWindow() {
mainWindow = new BrowserWindow({
width: 800,
height: 600,
title: '鸿蒙系统信息工具',
webPreferences: {
nodeIntegration: true, // 允许渲染进程使用Node.js API
contextIsolation: false, // 关闭上下文隔离(鸿蒙兼容必需配置)
preload: path.join(__dirname, 'preload.js') // 预加载脚本路径
},
// 适配鸿蒙窗口样式:去除默认边框,采用鸿蒙扁平化设计
frame: false,
titleBarStyle: 'hidden'
});
// 加载渲染进程页面(UI界面)
mainWindow.loadFile('index.html');
// 打开开发者工具(开发调试用,发布时可关闭)
mainWindow.webContents.openDevTools();
// 窗口关闭事件:释放窗口实例
mainWindow.on('closed', () => {
mainWindow = null;
});
}
// 监听渲染进程的"get-system-info"事件,查询系统信息并返回结果
ipcMain.on('get-system-info', async (event) => {
try {
// 查询系统基础信息(设备型号、系统版本等)
const osInfo = await si.osInfo();
// 查询CPU信息(型号、核心数等)
const cpuInfo = await si.cpu();
// 查询内存信息(总内存、已用内存等)
const memInfo = await si.mem();
// 整理鸿蒙设备适配的关键信息(提取核心字段,便于UI展示)
const systemInfo = {
deviceModel: osInfo.hostname, // 设备型号(鸿蒙设备hostname通常为设备型号)
osVersion: osInfo.version, // 系统版本(鸿蒙OS版本号)
cpuModel: cpuInfo.model, // CPU型号
cpuCores: cpuInfo.cores, // CPU核心数
memTotal: (memInfo.total / 1024 / 1024 / 1024).toFixed(2), // 总内存(GB)
memUsed: (memInfo.used / 1024 / 1024 / 1024).toFixed(2), // 已用内存(GB)
memUsage: (memInfo.used / memInfo.total * 100).toFixed(2) // 内存使用率(%)
};
// 向渲染进程发送查询结果
event.reply('system-info-reply', systemInfo);
} catch (error) {
console.error('查询系统信息失败:', error);
event.reply('system-info-reply', { error: '获取系统信息失败,请检查设备兼容性' });
}
});
// 监听关闭应用事件(来自渲染进程)
ipcMain.on('close-app', () => {
if (mainWindow) {
mainWindow.close();
}
});
// 应用就绪后创建窗口
app.whenReady().then(createWindow);
// 关闭所有窗口时退出应用(Windows/Linux平台)
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit();
}
});
// 激活应用时创建窗口(macOS平台,点击 dock 图标时)
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow();
}
});
(2)预加载脚本:preload.js(渲染进程与主进程通信桥接)
javascript
运行
const { ipcRenderer, contextBridge } = require('electron');
// 向渲染进程暴露安全的API,避免直接暴露Node.js API导致安全风险
contextBridge.exposeInMainWorld('electronAPI', {
// 获取系统信息的方法(返回Promise,便于异步调用)
getSystemInfo: () => {
return new Promise((resolve) => {
// 向主进程发送请求
ipcRenderer.send('get-system-info');
// 监听主进程的响应,获取结果后resolve
ipcRenderer.once('system-info-reply', (event, data) => {
resolve(data);
});
});
},
// 关闭应用的方法
closeApp: () => {
ipcRenderer.send('close-app');
}
});
(3)渲染进程页面:index.html(UI 界面 + 交互逻辑)
html
预览
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>鸿蒙系统信息工具</title>
<style>
/* 适配鸿蒙系统风格:简约、扁平化、高可读性 */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
font-family: "HarmonyOS Sans SC", "Microsoft YaHei", sans-serif;
}
body {
background-color: #f5f5f7;
color: #1d1d1f;
line-height: 1.5;
}
/* 窗口头部(鸿蒙风格标题栏) */
.window-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 12px 20px;
background-color: #ffffff;
border-bottom: 1px solid #e5e5e7;
}
.window-title {
font-size: 18px;
font-weight: 500;
color: #1d1d1f;
}
.window-controls {
display: flex;
gap: 16px;
}
.control-btn {
width: 32px;
height: 32px;
border: none;
background: transparent;
cursor: pointer;
border-radius: 50%;
transition: background-color 0.2s ease;
font-size: 16px;
}
.control-btn:hover {
background-color: #f0f0f2;
}
/* 主内容区容器 */
.container {
padding: 30px;
max-width: 700px;
margin: 0 auto;
}
/* 信息卡片(鸿蒙风格卡片设计) */
.card {
background-color: #ffffff;
border-radius: 12px;
padding: 24px;
margin-bottom: 20px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
}
.card-title {
font-size: 16px;
color: #86868b;
margin-bottom: 16px;
font-weight: 400;
}
/* 信息网格布局 */
.info-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 20px;
}
.info-item {
display: flex;
flex-direction: column;
}
.info-label {
font-size: 14px;
color: #86868b;
margin-bottom: 4px;
}
.info-value {
font-size: 16px;
font-weight: 500;
color: #1d1d1f;
}
/* 内存进度条 */
.memory-bar {
width: 100%;
height: 8px;
background-color: #f0f0f2;
border-radius: 4px;
margin-top: 8px;
overflow: hidden;
}
.memory-progress {
height: 100%;
background-color: #007aff;
border-radius: 4px;
transition: width 0.3s ease;
}
</style>
</head>
<body>
<!-- 窗口头部(适配鸿蒙风格,包含标题与关闭按钮) -->
<div class="window-header">
<div class="window-title">鸿蒙系统信息工具</div>
<div class="window-controls">
<button class="control-btn" onclick="window.electronAPI.closeApp()">✕</button>
</div>
</div>
<!-- 主内容区:分卡片展示系统信息 -->
<div class="container">
<!-- 设备基础信息卡片 -->
<div class="card">
<div class="card-title">设备基础信息</div>
<div class="info-grid">
<div class="info-item">
<span class="info-label">设备型号</span>
<span class="info-value" id="deviceModel">-</span>
</div>
<div class="info-item">
<span class="info-label">系统版本</span>
<span class="info-value" id="osVersion">-</span>
</div>
</div>
</div>
<!-- CPU信息卡片 -->
<div class="card">
<div class="card-title">CPU信息</div>
<div class="info-grid">
<div class="info-item">
<span class="info-label">CPU型号</span>
<span class="info-value" id="cpuModel">-</span>
</div>
<div class="info-item">
<span class="info-label">核心数</span>
<span class="info-value" id="cpuCores">-</span>
</div>
</div>
</div>
<!-- 内存信息卡片 -->
<div class="card">
<div class="card-title">内存信息</div>
<div class="info-grid">
<div class="info-item">
<span class="info-label">总内存</span>
<span class="info-value" id="memTotal">- GB</span>
</div>
<div class="info-item">
<span class="info-label">已用内存</span>
<span class="info-value" id="memUsed">- GB</span>
</div>
</div>
<div class="info-item" style="margin-top: 16px;">
<span class="info-label">内存使用率</span>
<span class="info-value" id="memUsage">- %</span>
<div class="memory-bar">
<div class="memory-progress" id="memoryProgress" style="width: 0%"></div>
</div>
</div>
</div>
</div>
<script>
// 页面加载完成后,主动获取系统信息并更新UI
window.addEventListener('DOMContentLoaded', async () => {
try {
// 调用预加载脚本暴露的API,获取系统信息
const systemInfo = await window.electronAPI.getSystemInfo();
// 处理错误情况
if (systemInfo.error) {
alert(systemInfo.error);
return;
}
// 更新UI显示系统信息
document.getElementById('deviceModel').textContent = systemInfo.deviceModel;
document.getElementById('osVersion').textContent = systemInfo.osVersion;
document.getElementById('cpuModel').textContent = systemInfo.cpuModel;
document.getElementById('cpuCores').textContent = systemInfo.cpuCores;
document.getElementById('memTotal').textContent = systemInfo.memTotal + ' GB';
document.getElementById('memUsed').textContent = systemInfo.memUsed + ' GB';
document.getElementById('memUsage').textContent = systemInfo.memUsage + ' %';
document.getElementById('memoryProgress').style.width = systemInfo.memUsage + '%';
} catch (error) {
console.error('获取系统信息失败:', error);
alert('获取系统信息失败,请检查设备连接或兼容性设置');
}
});
</script>
</body>
</html>
3. 代码核心说明
- 主进程(main.js):Electron 应用的核心,负责窗口创建、系统资源调用(通过 systeminformation 库查询硬件信息)、与渲染进程的通信管理,同时配置鸿蒙兼容必需的参数(如关闭上下文隔离)。
- 预加载脚本(preload.js):作为渲染进程与主进程的安全通信桥梁,通过
contextBridge暴露有限 API,既保证了通信安全性,又避免了直接暴露 Node.js API 带来的风险。 - 渲染进程(index.html):负责 UI 展示与用户交互,采用鸿蒙扁平化设计风格适配系统视觉,通过调用预加载脚本暴露的
electronAPI获取系统信息并动态更新页面。 - 鸿蒙适配关键要点:窗口样式去除默认边框、关闭上下文隔离以兼容鸿蒙 Linux 环境、打包为 Linux x64 架构应用(鸿蒙设备主流架构)。
四、调试与运行:在鸿蒙设备上测试应用
1. 本地调试(开发机上预览)
在项目根目录执行以下命令,启动应用进行本地调试(支持热重载,修改代码后无需重启应用):
bash
运行
npm start
启动后将自动打开应用窗口,显示开发机的系统信息,可在此阶段调试 UI 样式、功能逻辑是否正常。
2. 鸿蒙设备调试(关键步骤)
(1)打包 Linux 版本应用
由于鸿蒙 OS 兼容 Linux 环境,需将应用打包为 Linux x64 架构版本:
bash
运行
npm run package
打包完成后,项目根目录会生成dist文件夹,其中harmony-system-tool-linux-x64目录即为可在鸿蒙设备上运行的应用文件。
(2)将应用传输到鸿蒙设备
- 方式 1:USB 数据线传输:将开发机与鸿蒙设备通过 USB 连接,在鸿蒙设备上开启 “文件传输模式”,直接拷贝
harmony-system-tool-linux-x64文件夹到设备的任意目录(如 “文档” 文件夹)。 - 方式 2:网络共享传输:在开发机上开启文件夹共享,通过鸿蒙设备的 “文件管理” 应用访问共享文件夹,下载应用包。
(3)在鸿蒙设备上运行应用
- 打开鸿蒙设备的 “终端” 应用(需在开发者模式下启用,可在系统搜索中查找 “终端”)。
- 进入应用所在目录(以拷贝到 “文档” 文件夹为例):
bash
运行
cd /home/user/Documents/harmony-system-tool-linux-x64 # 替换为实际应用路径 - 赋予应用执行权限:
bash
运行
chmod +x harmony-system-tool - 启动应用:
bash
运行
./harmony-system-tool
启动成功后,鸿蒙设备上会自动打开应用窗口,展示设备的真实系统信息(如设备型号、鸿蒙 OS 版本、CPU / 内存占用等)。
3. 常见问题排查
| 问题现象 | 排查方向 | 解决方案 |
|---|---|---|
| 应用无法启动,终端提示 “权限不足” | 未赋予应用执行权限 | 执行chmod +x harmony-system-tool赋予执行权限 |
| 启动后白屏,无内容显示 | 上下文隔离未关闭或预加载脚本配置错误 | 检查 main.js 中contextIsolation: false是否配置,preload.js 路径是否正确 |
| 无法获取系统信息,报错 “module not found” | 依赖包未安装或安装不完整 | 重新执行npm install安装依赖,确保 systeminformation 包成功安装 |
| 鸿蒙设备无法识别应用,启动无响应 | 打包架构错误 | 确保打包命令中包含--platform=linux --arch=x64,鸿蒙设备多为 x64 架构 |
| 应用启动后闪退 | 鸿蒙 OS 版本过低 | 确认设备鸿蒙 OS 版本为 3.0 及以上,低版本不支持 Linux 兼容层 |
五、进阶优化:鸿蒙特性深度适配
1. 调用鸿蒙系统 API(如通知、文件选择)
通过electron-harmony-adapter插件可实现 Electron 应用调用鸿蒙原生 API,以系统通知为例:
(1)安装插件
bash
运行
npm install electron-harmony-adapter --save
(2)在 main.js 中添加通知功能
javascript
运行
const { HarmonyAdapter } = require('electron-harmony-adapter');
const path = require('path');
// 在createWindow函数中初始化鸿蒙适配器
function createWindow() {
// ... 原有窗口配置代码 ...
// 初始化鸿蒙适配器
const harmonyAdapter = new HarmonyAdapter(mainWindow);
// 示例:当内存使用率超过80%时发送系统通知
ipcMain.on('check-memory-usage', (event, usage) => {
if (usage > 80) {
harmonyAdapter.showNotification({
title: '内存使用率警告',
body: `当前内存使用率已达${usage}%,建议关闭不必要的应用释放内存`,
icon: path.join(__dirname, 'icon.png') // 通知图标(可选)
});
}
});
}
2. 适配鸿蒙深色模式
鸿蒙系统支持深色 / 浅色模式切换,需让应用自动适配该特性:在 index.html 的<script>标签中添加深色模式检测逻辑:
javascript
运行
// 检测鸿蒙系统深色模式
function adaptDarkMode() {
const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
if (isDarkMode) {
document.body.classList.add('dark-mode');
// 动态修改CSS变量适配深色模式
document.documentElement.style.setProperty('--bg-color', '#1a1a1a');
document.documentElement.style.setProperty('--card-bg-color', '#2c2c2e');
document.documentElement.style.setProperty('--text-color', '#f5f5f7');
document.documentElement.style.setProperty('--label-color', '#a1a1a6');
} else {
document.body.classList.remove('dark-mode');
document.documentElement.style.setProperty('--bg-color', '#f5f5f7');
document.documentElement.style.setProperty('--card-bg-color', '#ffffff');
document.documentElement.style.setProperty('--text-color', '#1d1d1f');
document.documentElement.style.setProperty('--label-color', '#86868b');
}
}
// 页面加载时适配一次
adaptDarkMode();
// 监听系统深色模式切换事件,实时适配
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', adaptDarkMode);
同时在 CSS 中添加深色模式样式:
css
:root {
--bg-color: #f5f5f7;
--card-bg-color: #ffffff;
--text-color: #1d1d1f;
--label-color: #86868b;
}
.dark-mode {
background-color: var(--bg-color);
color: var(--text-color);
}
.dark-mode .card {
background-color: var(--card-bg-color);
}
.dark-mode .info-label {
color: var(--label-color);
}
.dark-mode .window-header {
background-color: var(--card-bg-color);
border-bottom-color: #3a3a3c;
}
3. 打包为鸿蒙 HAP 安装包(可选,用于应用市场发布)
若需将应用发布到鸿蒙应用市场,可通过 DevEco Studio 将 Electron 应用打包为 HAP 格式:
- 打开 DevEco Studio,创建 “鸿蒙 Native 应用项目”,选择与设备匹配的 API 版本。
- 将 Electron 打包后的
harmony-system-tool-linux-x64文件夹复制到项目的libs目录下。 - 在项目的
config.json中配置应用基本信息(应用名称、图标、权限等):json
{ "app": { "bundleName": "com.example.harmonyelectron", "vendor": "example", "version": { "code": 10000, "name": "1.0.0" } }, "module": { "name": "entry", "type": "native", "srcPath": "./src/main", "mainElement": "MainAbility", "deviceTypes": ["phone", "tablet", "pc"], "abilities": [ { "name": "MainAbility", "srcPath": "./src/main/ability", "icon": "$media:icon", "label": "鸿蒙系统信息工具", "visible": true, "launchType": "standard" } ] } } - 配置启动脚本,让 HAP 包安装后自动启动 Electron 应用,具体可参考 DevEco Studio 官方文档中 “Native 应用集成第三方应用” 相关教程。
- 点击 DevEco Studio 的 “Build HAP” 按钮,生成鸿蒙安装包(.hap 文件),即可用于应用市场发布。
六、总结与展望
通过本文的实战教程,我们完成了从环境搭建、代码开发到调试部署的鸿蒙 Electron 应用全流程实践,核心收获包括:
- 理解了鸿蒙 OS 与 Electron 的结合原理 —— 基于 Linux 兼容层实现无缝适配,无需重构现有 Electron 技术栈。
- 掌握了鸿蒙 Electron 应用的关键开发技巧,包括环境配置、鸿蒙特性适配、跨端调试方法。
- 实现了一个可直接运行的实战项目,具备系统信息查询功能,可作为后续开发的基础模板。
未来,随着鸿蒙 OS 对 Linux 生态的进一步优化,Electron 与鸿蒙的结合将具备更广阔的应用场景:
- 现有 Electron 应用可低成本迁移至鸿蒙设备,无需放弃已有技术积累。
- 前端开发者可零门槛切入鸿蒙生态,复用 HTML/CSS/JS 技术栈快速开发跨端应用。
- 鸿蒙设备的桌面应用生态将持续丰富,覆盖工具类、办公类、娱乐类等更多场景。
如果本文对你有帮助,欢迎点赞、收藏、关注!后续将分享更多鸿蒙跨端开发实战技巧(如 Electron+Vue/React 适配鸿蒙、鸿蒙原生 API 深度集成等),敬请期待~
文末标签
#鸿蒙OS #Electron #跨端开发 #前端开发 #鸿蒙应用开发 #代码实战 #桌面应用开发
欢迎大家加入[开源鸿蒙跨平台开发者社区](https://openharmonycrossplatform.csdn.net),一起共建开源鸿蒙跨平台生态。
文章中添加一些关于鸿蒙系统的介绍
写一篇介绍鸿蒙系统的文章
推荐一些关于鸿蒙系统的优秀文章
更多推荐

所有评论(0)