用Electron跨平台框架在鸿蒙PC上开发沉浸光感应用:PrismHalo的平台适配、场景引擎与HAP交付实践
用Electron跨平台框架在鸿蒙PC上开发沉浸光感应用:PrismHalo的平台适配、场景引擎与HAP交付实践
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
基于 Electron 的鸿蒙化适配项目地址:https://atomgit.com/CPF-Electron/Electron
前言
在鸿蒙PC(HarmonyOS PC)上做桌面应用,很多开发者的第一反应是"是不是只能用 ArkTS?"。答案是:不必。借助 Electron 这套业界最成熟的跨平台框架,前端与 Node.js 开发者几乎可以零成本把自己的技术栈迁移到 鸿蒙PC 上——业务代码依旧是熟悉的 HTML/CSS/JS 与主进程脚本,产物则是一个标准签名 HAP,正常安装进 鸿蒙PC 真机运行。本文是笔者在 鸿蒙PC 上交付的第十六个跨平台框架实践项目,也是 Electron 线的第一个完整作品,项目定名 PrismHalo 沉浸光感。
PrismHalo 的产品隐喻是"把光装进桌面":内置星云漫游、晨雾流光、深海脉冲三个光场景,每个场景都可以独立调节光谱色相、发光强度、流动速度与呼吸律动,并配有一个 25 分钟的"光浴"专注计时器。整个应用的界面、状态机与持久化逻辑全部由 Electron 业务层承担,ArkTS 侧一行代码都不用改——这正是 Electron 跨平台框架在 鸿蒙PC 上最诱人的交付形态。
本文会从工程结构讲起,逐一拆解主进程的平台适配要点、可单测的场景引擎、从 app/ 到 signed.hap 的完整构建链路,以及真机运行效果,最后给出踩坑复盘。全部工程托管在 AtomGit 的开源鸿蒙PC开发者组织下,欢迎参考与共建。
关键词: Electron,跨平台框架,鸿蒙PC,HarmonyOS PC,libelectron.so,HAP,ArkTS,窗口适配,签名,场景引擎,专注计时,AtomGit,开源鸿蒙

一、为什么选 Electron 跨平台框架做鸿蒙PC应用
先建立正确的心智模型:鸿蒙PC 上的 Electron 不是独立可执行程序,而是跑在 HAP 应用包里的三明治结构:
| 组成 | 作用 | 体积 |
|---|---|---|
libelectron.so | Electron/Chromium/Node 引擎本体 | 约 187MB |
libadapter.so | 鸿蒙原生适配层(窗口、权限桥) | 数 MB |
| ArkTS 壳工程 | 应用入口、Ability、窗口承载 | 工程源码 |
开发者拿到的官方预编译包(AtomGit 上 CPF-Electron 项目的 v40.0.1 release,约 367MB,两层解压)已经把 ArkTS 壳与两枚动态库准备好了,业务代码放在 web_engine/src/main/resources/resfile/resources/app/ 目录下,由 libelectron.so 里的 Node 运行时加载。对这个跨平台框架而言,鸿蒙PC 只是一个新的目标平台:aarch64 架构、musl libc、窗口由 ArkTS 壳承载。
这里有一个最容易踩的坑必须先讲:不能 npm install electron。npm 官方 Electron 二进制面向 glibc 体系发布,而 鸿蒙PC 是 musl + aarch64 组合,装了也跑不起来。所以 PrismHalo 工程坚持零 npm 依赖——所有脚本只用 Node 内置能力,Electron API 由 HAP 内的引擎直接提供。这反而逼出了一个非常干净的工程形态。
对开发者的收益是直接的:界面用最熟悉的 Web 技术栈写一次;主进程逻辑用 Node 写;产物是标准 HAP,可以正常签名、安装到 鸿蒙PC 真机。相比纯 ArkTS 方案,Electron 跨平台框架让存量 Web 开发者几乎零成本进入 鸿蒙PC 生态。
二、PrismHalo 的双层工程结构
工程采用 app/ + hap/ 双层结构,业务层与壳层彻底解耦:
PrismHalo/
├── app/ # ★ Electron 业务层(你的应用,日常只改这里)
│ ├── main.js # 主进程:窗口、菜单、IPC、导航防护
│ ├── preload.js # contextBridge 最小暴露
│ ├── scene.mjs # 场景状态机 + 专注计时(纯函数,可单测)
│ ├── main-utils.cjs # 运行时信息与 URL 白名单校验
│ └── index.html / styles.css / renderer.mjs
├── hap/ # 官方 HAP 壳工程(hap:init 生成,约 209MB)
│ ├── electron/libs/arm64-v8a/ # libelectron.so / libadapter.so / libffmpeg.so
│ └── web_engine/.../resources/app/ # hap:sync 的同步目标
├── scripts/ # hap:init / hap:sign / hap:build 等流水线脚本
└── tests/ # node --test 单元测试(13 例)
日常主循环只有一条命令:npm run hap:dev,它串起 同步(app/ → 壳工程)→ 构建(hvigor 打包并签名)→ 安装(hdc install)→ 拉起(aa start) 四个阶段。icudtl.dat、*.pak、libelectron.so 这些运行时资源由官方包一次性提供,永远不动。
三、主进程:鸿蒙PC的平台适配与安全基线
Electron 代码要"看起来没 bug 地"跑在 鸿蒙PC 上,主进程有几处必须处理适配。PrismHalo 的 app/main.js 关键片段如下:
const path = require('node:path');
const { app, BrowserWindow, ipcMain, Menu, session } = require('electron');
const { getRuntimeInfo, isTrustedUrl } = require('./main-utils.cjs');
const indexPath = path.join(__dirname, 'index.html');
let mainWindow = null;
// 鸿蒙PC 上 platform 实测返回 'openharmony',也见过 'ohos',两个都要认
const isOhos = process.platform === 'ohos' || process.platform === 'openharmony';
function createWindow() {
mainWindow = new BrowserWindow({
title: 'PrismHalo · 沉浸光感',
width: 1440,
height: 900,
backgroundColor: '#07090d',
show: false,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: false, // 鸿蒙 Electron 模板的默认取值
webSecurity: true
}
});
mainWindow.once('ready-to-show', () => {
mainWindow?.show();
});
mainWindow.loadFile(indexPath).catch((error) => {
console.error('[prismhalo] loadFile 失败:', error.message);
// 退路:转成 file:// URL 再加载一次
mainWindow?.loadURL(pathToFileURL(indexPath).href);
});
}
app.whenReady().then(() => {
// 鸿蒙PC 窗口自带系统菜单区,应用菜单必须置空,否则叠成两层
if (isOhos) {
Menu.setApplicationMenu(null);
}
ipcMain.handle('runtime:get', (event) => {
if (!isTrustedUrl(event.senderFrame?.url, indexPath)) {
throw new Error('Untrusted IPC sender');
}
return getRuntimeInfo(app, process);
});
createWindow();
});
这段代码浓缩了四条 鸿蒙PC 实测经验:
process.platform返回openharmony或ohos,不是linux,两个值都要识别,任何平台分支判断都要据此改写;- 鸿蒙PC 窗口自带系统菜单区,应用再
setApplicationMenu会叠出两层菜单,必须在鸿蒙上置空; loadFile挂上loadURL(file://)退路,兜住壳工程资源路径解析的边界情况;- IPC 通道做发送方白名单校验,
isTrustedUrl只放行本地入口页面,陌生的senderFrame一律拒绝。
preload 侧则只暴露一个最小接口,把渲染层与 Electron 内核隔离开:
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('prism', {
getRuntime: () => ipcRenderer.invoke('runtime:get')
});
渲染层调 window.prism.getRuntime(),就能拿到 platform、electron、chromium、node 等版本信息——真机截图里左下角的 RUNTIME LIVE 面板显示的正是这份数据,它也顺带成了"Electron 引擎确实在 鸿蒙PC 上运行"的最直观证据。
四、场景引擎与专注计时:纯函数先行
光场景的状态逻辑是 PrismHalo 的核心资产,这部分刻意写成零依赖纯函数,与 Electron API 完全解耦,既方便单测覆盖,也方便浏览器里直接预览:
export const PRESETS = Object.freeze([
Object.freeze({ id: 'nebula', name: '星云漫游', hue: 262, intensity: 78, tempo: 36 }),
Object.freeze({ id: 'dawn', name: '晨雾流光', hue: 32, intensity: 64, tempo: 22 }),
Object.freeze({ id: 'abyss', name: '深海脉冲', hue: 184, intensity: 72, tempo: 48 })
]);
export function clamp(value, minimum, maximum, fallback = minimum) {
const numeric = Number(value);
if (!Number.isFinite(numeric)) {
return fallback;
}
return Math.min(maximum, Math.max(minimum, Math.round(numeric)));
}
export function normalizeScene(input = {}) {
const candidate = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
const preset = PRESETS.some((item) => item.id === candidate.preset)
? candidate.preset
: DEFAULT_SCENE.preset;
return {
preset,
hue: clamp(candidate.hue, 0, 360, DEFAULT_SCENE.hue),
intensity: clamp(candidate.intensity, 20, 100, DEFAULT_SCENE.intensity),
tempo: clamp(candidate.tempo, 10, 80, DEFAULT_SCENE.tempo),
breathing: typeof candidate.breathing === 'boolean' ? candidate.breathing : DEFAULT_SCENE.breathing
};
}
export function toggleTimer(timer, now) {
if (timer.endAt !== null) {
const remaining = getRemaining(timer, now);
return { ...timer, remaining, endAt: null };
}
const remaining = timer.remaining > 0 ? timer.remaining : timer.duration;
return { ...timer, remaining, endAt: now + remaining * 1000 };
}
normalizeScene 是所有状态变更的必经关口:无论输入来自 UI 滑块、本地存储恢复还是 IPC,色相被裁到 0–360、强度被裁到 20–100、速度被裁到 10–80,非法输入一律回退默认值。状态规整收口在一处,渲染层拿到的永远是合法光场,持久化也不会写进脏数据。专注计时器同样用 duration/remaining/endAt 三字段纯函数建模,暂停即冻结 remaining、恢复即重算 endAt,可测试性与真实交互一一对应。
值得一提的还有一个 鸿蒙PC 特有约束:HAP 内的应用目录只读,任何可写数据(比如光场偏好的持久化)都必须走 app.getPath('userData') 指向的沙箱目录,直接往安装目录写文件必然失败。
五、构建链路:从 app/ 到 signed.hap
构建是 Electron 跨平台框架落地 鸿蒙PC 最"劝退"的一段,PrismHalo 把它固化成了三条命令。
第一步,初始化壳工程:下载 AtomGit 上 CPF-Electron v40.0.1 预编译包,两层解压后执行 npm run hap:init,脚本负责校验官方结构、整体复制进 hap/、改写包名,并修复搬迁导致的 oh_modules 符号链接失效(否则构建报 00308018)。
第二步,签名:npm run hap:sign 整组复用本机 DevEco 自动签名材料——.p12 证书、.cer、.p7b profile 三件套加上配套工程的 signingConfigs 密文,按"材料、密文、包名三者绑定"的规则写进 hap/build-profile.json5。这里有个文档里很少提的细节:modelVersion 5.0.0 的 schema 只允许根级出现 app 与 modules,signingConfigs 必须放在 app 对象内部,放错位置会得到一个毫无提示指向性的 00303038 校验错误。
第三步,构建:用纯 Node 跑 hvigor,绕开 鸿蒙PC Toybox 环境没有 bash 语义的问题:
DEVECO_SDK_HOME=$HMOS_CLT_HOME/sdk \
node $HMOS_CLT_HOME/hvigor/bin/hvigorw.js assembleHap \
--mode module -p product=default -p module=electron@default --no-daemon
两个易错点:不设 DEVECO_SDK_HOME 会报 00303217;新解压的壳工程没有 oh_modules,要先 ohpm install 把本地 HAR 依赖装齐。产出 electron-default-signed.hap 约 210MB——其中 187MB 是 libelectron.so,属于正常体积,不必惊慌。
安装环节还有一个真机大坑值得单独记录:壳工程默认声明了五个 ACL 受限权限(读写下载/文档/桌面目录、读剪贴板、系统悬浮窗),而调试证书的 acls 列表为空,bm install 直接报 9568289 grant request permissions failed。调试期解法是在 web_engine/src/main/module.json5 里把这五个权限裁掉再重打包;正式发布则应走 AppGallery Connect 申请受限权限后重签。
六、真机运行效果
以下截图均来自 鸿蒙PC 真机(画面中可见系统顶部状态栏与底部 Dock 栏),应用为标准签名 HAP 安装运行,顶栏徽标清晰标注 openharmony · Electron v40.0.1-release。
图 1:启动进入"星云漫游"。 深紫光晕球体悬浮于三栏布局中央,右侧参数面板显示色相 262°、强度 78%、速度 36;左下角 RUNTIME LIVE 面板正在汇报 Electron、Chromium、Node 的引擎版本。

图 2:切换"晨雾流光"。 点击左侧场景卡片,球体转为柔和琥珀色,参数面板同步跳到色相 32°、强度 64%、速度 22——场景切换即一次 applyPreset 状态归一。

图 3:切换"深海脉冲"。 冷青蓝波光接管主视觉,色相 184°、强度 72%、速度 48,呼吸律动默认开启,光强随呼吸缓慢起伏。

图 4:25 分钟"光浴"计时进行中。 点击"开始光浴"后计时器读数走到 24:58,主按钮已切换为"暂停光浴",呼吸律动开关呈亮青色——纯函数计时器在 鸿蒙PC 真机上稳定运行。

图 5:光浴持续中。 计时继续走秒,界面保持深色沉浸主题,鸿蒙PC 底部 Dock 栏与顶部状态栏完整可见,Electron 窗口与系统桌面环境融为一体。

图 6:沉浸光感全貌。 三栏布局、光场景卡片、参数微调与专注计时一屏尽收,RUNTIME LIVE 持续在线——这就是一个标准 Electron 应用跑在 鸿蒙PC 上的完整模样。

七、测试与回归基线
跨平台框架开发的纪律是:平台适配代码靠真机验证,业务逻辑靠单元测试。PrismHalo 用 Node 内置的 node --test 挂了 13 个用例,覆盖 normalizeScene 的非法输入回退与越界裁剪、applyPreset 的预设切换与未知预设保持、计时器的开始/暂停/恢复/归零、formatDuration 的分秒格式,以及 isTrustedUrl 对本地入口放行、远程页面拒绝等安全边界。
工程还配了一个 npm run verify 静态检查层:语法检查全部 JS、sh -n 检查全部脚本、CSP 安全基线校验,并固化了几条 鸿蒙PC 专属断言——Menu.setApplicationMenu(null) 必须存在、openharmony 与 ohos 双值识别必须存在、禁止引入 npm 标准 Electron 依赖。当前 13 用例全绿,构建链路一条命令可复现。
八、复盘与展望
PrismHalo 作为 Electron 跨平台框架在 鸿蒙PC 上的第一个完整交付,沉淀了三条可复用的经验:
- 信任边界收口:平台差异(菜单叠加、platform 取值、只读目录)全部收在主进程一处,渲染层与业务层保持平台无关,未来平台行为变化只需要改一个文件;
- 纯函数状态机先行:场景规整与计时逻辑与 Electron API 解耦,13 个单测在无真机环境下即可回归,构建上真机只是最后一跳;
- 构建链路脚本化:初始化、签名、构建、安装全部固化成
npm run hap:*脚本,ACL 权限、signingConfigs 位置这类深坑修一次就永久免疫。
Electron 40 已经在 鸿蒙PC 上跑通了从窗口、IPC 到 Chromium 渲染的完整链路,Web 生态里数以百万计的既有应用与组件,理论上都可以循着这条路径进入开源鸿蒙PC 生态。如果你也想在 鸿蒙PC 上用 Electron 跨平台框架做出自己的应用,欢迎到 AtomGit 的 OpenHarmonyPCDeveloper 组织申请新建项目,一起把这个生态做厚。
更多推荐




所有评论(0)