这篇文章是一篇面向初学者的 Electron 入门教程，目标是帮助开发者从零搭建一个最简单的 Electron 桌面应用。主要内容包括：

📌 适用人群：前端开发者、鸿蒙初学者、想用 Web 技术开发跨平台桌面应用的同学
🔧 关键词：#鸿蒙 #Electron #OpenHarmony #桌面应用 #JavaScript
✅ 本文特点：手把手教学 + 完整代码 + 鸿蒙适配要点 + 版本避坑指南

前言

你是否知道？除了手机和平板，鸿蒙系统（HarmonyOS/OpenHarmony）也正在向 PC 和桌面端拓展！而作为前端开发者，我们完全可以用熟悉的 HTML/CSS/JavaScript 技术，借助 Electron 框架，快速构建运行在鸿蒙 PC 上的桌面应用。

VS Code、Slack、Discord 等知名软件都是基于 Electron 开发的。现在，我们也能让 Electron 应用“跑”在鸿蒙系统上！

本文将带你 从零搭建一个能在鸿蒙 PC 上运行的 Electron 应用，并展示如何适配鸿蒙特有的路径与资源加载机制。

💡 提示：本文属于专栏《Electron for OpenHarmony》系列，后续将深入讲解打包、IPC 通信、性能优化等进阶内容。

一、准备工作

1. 安装 Node.js（关键！注意版本）

截至 2025 年 11 月，Electron 最高仅支持 Node.js v20.x，不兼容 v22+。鸿蒙开发环境对 Node 版本同样敏感。

✅ 推荐安装：Node.js v20.14.0（LTS）

🔗 下载地址：https://nodejs.org/dist/v20.14.0/node-v20.14.0-x64.msi

安装完成后，在终端验证：

1node -v  # 应输出 v20.14.0
2npm -v   # 建议使用 npm@10.8.0

⚠️ 如果你已安装高版本 Node，请先卸载，再安装 v20.x！

2. 创建项目目录

在桌面新建文件夹 harmony-electron-app，并用 VS Code 打开：

1mkdir harmony-electron-app
2cd harmony-electron-app
3npm init -y

此时会生成 package.json 文件。

二、安装 Electron

使用 npm 安装 Electron 作为开发依赖：

1npm install --save-dev electron

🇨🇳 国内用户可使用 cnpm 加速：

1npm install -g cnpm --registry=https://registry.npmmirror.com
2cnpm install --save-dev electron

验证安装成功：

1npx electron --version  # 如输出 v31.0.0+

三、编写主进程代码（main.js）

在项目根目录创建 main.js：

1// main.js
2const { app, BrowserWindow } = require('electron');
3const path = require('path');
4
5function createWindow() {
6  const win = new BrowserWindow({
7    width: 900,
8    height: 600,
9    webPreferences: {
10      preload: path.join(__dirname, 'preload.js'),
11      // 鸿蒙适配建议：关闭 nodeIntegration，启用 contextIsolation
12      nodeIntegration: false,
13      contextIsolation: true
14    }
15  });
16
17  // 加载本地 HTML
18  win.loadFile('index.html');
19}
20
21app.whenReady().then(() => {
22  createWindow();
23
24  app.on('activate', () => {
25    if (BrowserWindow.getAllWindows().length === 0) {
26      createWindow();
27    }
28  });
29});
30
31app.on('window-all-closed', () => {
32  if (process.platform !== 'darwin') {
33    app.quit();
34  }
35});

📌 鸿蒙安全建议：始终设置 contextIsolation: true，并通过 preload.js 暴露有限 API。

四、创建页面内容（index.html）

1<!-- index.html -->
2<!DOCTYPE html>
3<html lang="zh-CN">
4<head>
5  <meta charset="UTF-8" />
6  <title>鸿蒙上的 Electron 应用</title>
7  <style>
8    body {
9      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
10      display: flex;
11      flex-direction: column;
12      justify-content: center;
13      align-items: center;
14      height: 100vh;
15      margin: 0;
16      background: linear-gradient(135deg, #6a11cb 0%, #2575fc 100%);
17      color: white;
18    }
19    .card {
20      background: rgba(255, 255, 255, 0.1);
21      backdrop-filter: blur(10px);
22      padding: 30px;
23      border-radius: 16px;
24      text-align: center;
25    }
26  </style>
27</head>
28<body>
29  <div class="card">
30    <h1>🎉 Hello, HarmonyOS!</h1>
31    <p>这是一个运行在鸿蒙 PC 上的 Electron 应用</p>
32    <hr style="margin: 20px 0; opacity: 0.5;" />
33    <p>Chromium: <span id="chrome-version"></span></p>
34    <p>Node.js: <span id="node-version"></span></p>
35    <p>Electron: <span id="electron-version"></span></p>
36  </div>
37
38  <script src="./renderer.js"></script>
39</body>
40</html>

五、添加预加载脚本（preload.js）

出于安全考虑，渲染进程不能直接访问 Node.js。我们通过 preload.js 暴露必要信息：

1// preload.js
2const { contextBridge } = require('electron');
3
4contextBridge.exposeInMainWorld('versions', {
5  chrome: process.versions.chrome,
6  node: process.versions.node,
7  electron: process.versions.electron
8});

然后在渲染进程中读取：

1// renderer.js
2document.getElementById('chrome-version').innerText = window.versions.chrome;
3document.getElementById('node-version').innerText = window.versions.node;
4document.getElementById('electron-version').innerText = window.versions.electron;

✅ 这种方式比直接开启 nodeIntegration 更安全，符合鸿蒙应用上架规范。

六、配置启动脚本

修改 package.json：

1{
2  "name": "harmony-electron-app",
3  "version": "1.0.0",
4  "description": "A simple Electron app for HarmonyOS",
5  "main": "main.js",
6  "scripts": {
7    "start": "electron ."
8  },
9  "devDependencies": {
10    "electron": "^31.0.0"
11  }
12}

七、运行应用

在项目根目录执行：

1npm start

你会看到如下窗口（建议配图）：

📷 【此处插入运行效果图】

图注：应用成功运行，显示鸿蒙欢迎语及各组件版本号

八、鸿蒙适配特别说明

虽然 Electron 应用本身是跨平台的，但在 鸿蒙 PC 环境下需注意：

问题 解决方案
资源路径不同 使用 app.getAppPath() 获取真实路径
publicPath 加载失败（如用 Webpack） 动态设置 __webpack_require__.p（参考 MarkText 鸿蒙适配方案）
权限限制 避免直接调用 fs、child_process，通过主进程代理

🔜 后续文章将详解：如何用 electron-builder 打包鸿蒙安装包（.hap 或 .exe）

九、项目结构总结

1harmony-electron-app/
2├── main.js          # 主进程
3├── preload.js       # 预加载脚本（安全桥接）
4├── renderer.js      # 渲染进程逻辑
5├── index.html       # 页面
6└── package.json     # 配置文件

十、总结

通过本文，你已经成功：

  • 搭建了兼容鸿蒙的 Electron 开发环境
  • 创建了一个安全、美观的桌面应用
  • 掌握了主/渲染进程通信的最佳实践

Electron 让 Web 开发者也能轻松进军桌面端，而鸿蒙生态的扩展，为我们打开了新的应用场景。一套代码，多端运行——这正是现代开发的魅力所在！

📚 参考资料
Electron 官方文档
《从零开始：用 Electron 构建你的第一个桌面应用》（CSDN）
OpenHarmony 官方社区：https://gitee.com/openharmony

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

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

更多推荐

cover

KMP 实现鸿蒙跨端：Kotlin JSON 美化和分析器

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

KMP 实现鸿蒙跨端：Kotlin 数字计算器算法

avatar 人工智能6S服务平台

开源鸿蒙跨平台开发学习笔记 】DAY06：Flutter组件详解

虽然本小鱼开始对 Flutter 一点点也了解，但是这几天看了很多博客/文档，小鱼对Flutter的总结是：1个widget类、 2种状态类型，4棵渲染树。Widget不仅是按钮、文本等UI“控件”，也包括布局、手势检测、主题等功能性组件，整个App的界面和功能都通过 Widget 嵌套 Widget 的方式组合而成。Flutter中“万物皆为Widget” widget 的功能是“描述一个UI元

avatar 人工智能6S服务平台