Electron 跨平台框架实战:在鸿蒙 PC 用 CogBay 齿湾调度文件、外设与系统能力
Electron 跨平台框架实战:在鸿蒙 PC 用 CogBay 齿湾调度文件、外设与系统能力
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言
桌面应用的功能列表可以列得很长,但真正需要向操作系统要的东西并不多:用户愿意交出的文件、插上来就能用的外设、以及电量与剪贴板这类系统级状态。剩下的工作,是把这三类能力组织成用户愿意每天打开的界面。
这篇文章的样本叫 CogBay(齿湾),是一个在鸿蒙 PC 上使用 Electron 跨平台框架 开发的鸿蒙 PC 应用。它把文件当作进湾的货件、把外设当作泊位上的器械、把电量与系统能力当作仪表盘上的脉搏,用一张三栏作业台把三类调用收进同一个工作区:左栏「外设泊位」,中栏「文件枢纽台」,右栏「系统脉搏」。整套业务代码不依赖任何 npm 版 Electron 二进制,最终以 HAP 应用包的形式跑在鸿蒙 PC 桌面上。
「Electron 能跑在鸿蒙 PC 上」已经被验证过很多次,这里不再复述,而是想把三件更具体的事讲透:
- 在鸿蒙 PC 上,Electron 应用的能力边界画在哪一层——哪些调用必须经过主进程,哪些可以留在渲染层;
- 文件、外设、系统能力这三条链路,如何被拆成可测试的纯函数,而不是散成一堆事件回调;
- 这条链路上几个只在鸿蒙 PC 上出现、在 Windows / macOS 上永远遇不到的坑。
关键词:鸿蒙 PC、Electron、跨平台框架、文件系统调用、外设管理、系统能力调用、HAP 打包、IPC 安全、AtomGit

上图就是最终形态。鸿蒙 PC 桌面下方挂着系统 Dock,背后还开着 DevEco Studio,前景是 CogBay 的窗口。中栏「文件枢纽台」里已经入湾 8 件货件,合计 21 GB,既有 1.6 GB 的封装包,也有 115 KB 的表格;左栏「外设泊位」停着航标键盘、操舵手柄、钤印打印机、听浪耳机四件器械,下方带宽分舱表按权重自动切成了 74 / 111 / 185 / 111 Mbps;右上角的运行时徽标写着 CogBay v0.1.0 · openharmony/arm64。这行字不是写死的文案,而是主进程通过 IPC 现取的 process.platform 与 process.arch 原样回显——它是判断「应用到底跑在哪个平台」最不容易骗人的方式。
一、先看清落点:鸿蒙 PC 上的 Electron 应用是一个 HAP 包
带着桌面端 Electron 的直觉上手,第一步就容易走错。鸿蒙 PC 上的 Electron 应用不是一个 app.exe 那样的独立二进制,而是一个 HAP 应用包。包里装的是三样东西:
| 组成 | 职责 |
|---|---|
libelectron.so | Electron / Chromium 主引擎(含 Node 运行时),业务 JS 跑在它里面 |
libadapter.so | 鸿蒙原生适配层,把窗口、权限、系统能力桥接给 JS |
| ArkTS 壳工程 | 应用入口、Ability、窗口承载、权限声明 |
也就是说,你在这个跨平台框架里写下的业务代码,最终落点是 HAP 里 web_engine/src/main/resources/resfile/resources/app/ 这个目录,由包内的 libelectron.so 解释执行。CogBay 的构建产物实测约 210 MB,绝大部分体积来自这颗被裁剪过的引擎,而不是业务代码。这一个事实能推出后面所有设计约束:
- 没有 npm 上的 Electron 二进制。
npm i -D electron在鸿蒙 PC 上没有意义,工程里连devDependencies.electron都不该出现。CogBay 的静态检查脚本把这条写成了硬性门禁,一旦有人顺手装上,npm run verify直接失败。 - 系统能力由适配层接管。原生文件对话框、剪贴板、外设枚举这些能力,最终都要在主进程落地,渲染层只能通过 preload 拿到的窄接口去请求。
- 包体积与安装时间按两百兆量级预估。第一次安装会比桌面端慢一个数量级,等待期间不要误以为进程卡死而反复重试,重复安装还可能撞上签名与版本冲突。
工程里所有和鸿蒙 PC 相关的路径、包名、模块名都不硬编码,而是集中在 hap.config.json 这一个配置源:
{
"bundleName": "com.mosaic.windowlab",
"moduleName": "electron",
"abilityName": "EntryAbility",
"productName": "default",
"sdkBranch": "v40.0.1",
"runtimeDirectory": "web_engine/src/main/resources/resfile/resources",
"hmosCltHome": "/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0"
}
runtimeDirectory 决定业务代码同步到 HAP 的哪个目录,moduleName 与 productName 决定构建命令和产物路径,bundleName 决定 aa start 的 -b 参数。改任何一个,只改这一处。
还有一个必须记住的细节:process.platform 在鸿蒙 PC 上实测返回 'openharmony',也见过返回 'ohos' 的情况。所以任何平台判定都要写成双认,不能只写一个:
// app/main.js —— 平台判定必须双认,否则能力分支会静默走错
const isOhos = process.platform === 'ohos' || process.platform === 'openharmony';
二、把系统能力收进主进程的一道窄门
CogBay 把这条纪律执行得很彻底。鸿蒙 PC 上的 Electron 这个跨平台框架沿用了上游「主进程 + 渲染进程 + preload 桥」的模型,但适配层把系统能力收得更集中:窗口、文件、剪贴板、外设访问,最终都要在主进程落地。渲染层看到的不是能力本身,而是一扇被 preload 收窄的门。
CogBay 把这扇门收窄到了只有两个方法:
// app/preload.js —— 渲染层能看到的全部能力
'use strict';
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('cogbay', {
getRuntime: () => ipcRenderer.invoke('runtime:get'),
calibratePointer: (point) => ipcRenderer.invoke('bay:calibrate', point)
});
两个方法各守一条链路。getRuntime 只回传应用名、版本、平台、架构、Node 版本与主机名,供右上角徽标展示;calibratePointer 负责把渲染层送来的触点坐标夹取到合法范围,再回给调度链。为什么触点也要过一次主进程?因为坐标是外部输入,一旦越界,后面的命中判定、日志、甚至原生调用都可能拿到脏数据。把它放在主进程的纯函数里夹一次,比在渲染层各处重复判断可靠得多:
// app/main-utils.cjs —— 触点坐标夹取(纯函数,可单测)
const POINTER_LIMITS = { x: 0, y: 0, w: 20000, h: 20000 };
function clampPointer(pointer) {
if (!pointer || typeof pointer !== 'object') {
return null;
}
const x = Number(pointer.x);
const y = Number(pointer.y);
if (!Number.isFinite(x) || !Number.isFinite(y)) {
return null;
}
return {
x: Math.min(Math.max(Math.round(x), POINTER_LIMITS.x), POINTER_LIMITS.w),
y: Math.min(Math.max(Math.round(y), POINTER_LIMITS.y), POINTER_LIMITS.h)
};
}
主进程这一侧,窗口的五个安全开关各有明确取值,没有一个是随手写的:
// app/main.js(节选)
mainWindow = new BrowserWindow({
title: 'CogBay · 齿湾',
width: 1560,
height: 980,
minWidth: 720,
minHeight: 560,
backgroundColor: '#0a1430',
show: false,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true, // 渲染层拿不到 Node
nodeIntegration: false, // 页面里没有 require
sandbox: false, // preload 自己需要 require('electron')
webSecurity: true,
allowRunningInsecureContent: false
}
});
sandbox: true 看起来更安全,但 preload 里 require('electron') 会失效,桥就搭不起来。所以这里的选择是:关沙箱、开隔离——隔离负责让页面拿不到 Node,沙箱的职责交给「页面只加载本地 file:// 且 CSP 锁死」来兜。配套还有三道闸门:拒绝一切 web 权限申请、拒绝任何新窗口与跳转、每个 IPC 先校验发送方身份。校验方式不是比对域名,而是把候选 URL 与入口 index.html 的 file:// 规范化结果逐个对齐;本地应用的合法来源只有那一个入口,多一个都算越界。
另有一行代码,是只在鸿蒙 PC 上才需要写的,位置在 app.whenReady() 里:
// 鸿蒙 PC 窗口自带系统菜单区,应用内菜单必须置空,否则叠成两层
Menu.setApplicationMenu(null);
漏掉它,标题栏下方会同时出现应用菜单与系统菜单,两条叠在同一个位置,体验直接崩掉。这条约束同样被静态检查脚本抓住了——一旦有人删掉它,npm run verify 会失败,而不是等到上屏才发现。
空载状态下的三栏骨架如下。注意右上角徽标里的 openharmony/arm64,以及右栏「能力矩阵」中对浏览器预览模式的降级说明:

三、业务规则下沉:一个双端复用的 gearbay.mjs
边界靠自觉维护迟早会走样,真正让结构稳定的办法,是把所有会变的东西压进纯函数。CogBay 的 app/gearbay.mjs 是一个不 import electron、也不碰 DOM 的模块,浏览器和 Electron 两端共用同一份代码:
- 文件:
classifyFile/formatBytes/filterFiles/sortFiles(中文排序)/dedupeScan/transferPlan; - 外设:
DEVICE_CATALOG/attachDevice/detachDevice/bandwidthAlloc(按权重分舱)/deviceHealth; - 系统:
powerPlan/capabilityMatrix(真机与浏览器预览的能力降级说明); - 日志:
createBayLog/pushBayLog。
这个模块带来的第一个收益是测试成本。node --test 不需要启动 Electron,也不需要连着鸿蒙 PC,近二十条用例三秒钟跑完。它们覆盖的是最容易出错、又最难在界面上复现的边界:同名同大小的文件怎么成组、NaN 体积怎么兜底、带宽按权重分配后总和是否守恒、省航档位下哪些能力必须停用。把逻辑「沉」到纯函数里,测试就从「每次上屏验证」降到了「每次保存验证」。
第二个收益是双端预览。同一个 index.html 既能在鸿蒙 PC 的 Electron 里跑,也能用浏览器直接双击打开。预览模式下 window.cogbay 是 undefined,能力矩阵会自动切到「浏览器预览为模拟」的说明文案,而文件拖拽、去重巡检、启运估算这些纯逻辑照常工作。一份不用改就能在三处跑起来的代码,比任何界面都更接近跨平台的本质;依赖框架 API 的那薄薄一层,反而是最容易替换的部分。
四、文件枢纽台:拖入、去重、启运三段式
文件链路天然是异步加事件驱动,最容易写成一大团回调。CogBay 的拆法是:取文件的地方不判断,判断的地方不取文件。
渲染层只做两件事——接住拖拽进来的 File 对象、把 name / size / lastModified 三个字段送进调度链:
// app/renderer.mjs(节选)
zone.addEventListener('drop', (event) => {
event.preventDefault();
zone.classList.remove('over');
const dropped = [...(event.dataTransfer?.files || [])].map((f) => ({
name: f.name,
size: f.size,
mtime: f.lastModified || Date.now()
}));
if (dropped.length === 0) {
logBay('file', '拖入内容为空,未入湾');
return;
}
addFiles(dropped, '拖拽');
});
真正的判断都在纯函数里。文件先按扩展名归入影像、文书、影音、封装四类,再按关键词与视图双过滤;排序用 localeCompare(..., 'zh-CN'),中文文件名才不会出现「乙排在甲前面」这种意外。
去重不是逐对比对,而是给每个文件算一个「同名 + 同大小」的指纹,再把指纹相同的文件装进同一个桶:
// app/gearbay.mjs —— 同名同大小视为候选重复
export function dedupeScan(files) {
if (!Array.isArray(files)) {
return [];
}
const buckets = new Map();
for (const file of files) {
if (!file?.name) {
continue;
}
const key = `${file.name}::${Number(file.size) || 0}`;
if (!buckets.has(key)) {
buckets.set(key, []);
}
buckets.get(key).push(file);
}
return [...buckets.values()].filter((group) => group.length > 1);
}
这个指纹很轻,只读元数据、不读文件内容,所以拖入几百件也不会卡住界面。它的语义要诚实:只能标出「疑似重复」,不能断言内容一致。真正的强校验需要哈希,那属于下一阶段的慢路径;先用轻指纹把可疑集合圈出来,再让用户决定是否深检,是更符合桌面应用习惯的分层。
启运外发则是一个纯估算函数:按 80 Mbps 的链路速度换算耗时,再按 64 MB 一批切分批次,让用户对「这一批要等多久」有预期:
// app/gearbay.mjs —— 传输耗时与批次估算
export function transferPlan(files, speedMbps = 80) {
if (!Array.isArray(files) || files.length === 0) {
return { totalBytes: 0, seconds: 0, batches: 0, label: '无传输任务' };
}
const totalBytes = files.reduce((sum, f) => sum + (Number(f?.size) || 0), 0);
const mbps = Math.max(1, Number(speedMbps) || 1);
const seconds = totalBytes * 8 / (mbps * 1024 * 1024);
const batchBytes = 64 * 1024 * 1024;
const batches = Math.max(1, Math.ceil(totalBytes / batchBytes));
return {
totalBytes,
seconds: Math.round(seconds * 10) / 10,
batches,
label: `${formatBytes(totalBytes)} · 约 ${seconds < 1 ? '<1' : Math.round(seconds)} 秒 · ${batches} 批`
};
}
注意单位:totalBytes * 8 先把字节换成比特,再除以「Mbps × 1024 × 1024」,否则算出来的时间会差八倍。这种错误在界面上看不出来——用户只会觉得「进度条怎么走这么快」——只有把公式抽成纯函数、写成用例,才拦得住。
五、外设泊位:不可变登记表与按权重分舱
外设这条链路,难点从来不在 API 调用本身,而在状态。设备可能在你操作到一半时被拔掉,可能一次插进来三件,也可能某一类设备把带宽吃满。这些情况一旦散落在事件回调里,分支必然漏。
CogBay 的做法是把泊位抽象成一个不可变登记表 + 四个纯函数:靠泊、离泊、分舱、健康判定。每个函数要么返回新对象,要么返回原对象表示这次操作被拒绝——没有「部分成功」这种中间态:
// app/gearbay.mjs —— 靠泊返回新登记表,历史最多留 30 条
export function attachDevice(registry, deviceId) {
if (!registry || !Array.isArray(registry.berthed)) {
return registry;
}
const device = DEVICE_CATALOG.find((d) => d.id === deviceId);
if (!device || registry.berthed.some((d) => d.id === deviceId)) {
return registry;
}
return {
...registry,
berthed: [...registry.berthed, { ...device }],
history: [{ id: device.id, action: 'attach', at: Date.now() }, ...registry.history].slice(0, 30)
};
}
DEVICE_CATALOG 是六件器械的静态目录,每件带 type(输入 / 存储 / 输出 / 音频)、weight(类型权重)和 battery(无线设备电量,有线为 null)。权重不是装饰字段,它直接决定带宽怎么切:
// app/gearbay.mjs —— 按类型权重切分总带宽
export function bandwidthAlloc(berthed, totalMbps = 480) {
if (!Array.isArray(berthed) || berthed.length === 0) {
return [];
}
const total = berthed.reduce((sum, d) => sum + (Number(d.weight) || 1), 0);
const budget = Math.max(1, Number(totalMbps) || 1);
return berthed.map((device) => ({
id: device.id,
name: device.name,
mbps: Math.round(budget * ((Number(device.weight) || 1) / total))
}));
}
这套算法在真机截图里可以逐帧对上。只靠一件航标键盘(权重 2)时,它独占 480 Mbps;再加上操舵手柄(权重 3),总权重变成 5,于是切出 192 / 288 Mbps;再靠泊钤印打印机(权重 5),总权重 10,变成 96 / 144 / 240;最后加进听浪耳机(权重 3),总权重 13,落到 74 / 111 / 185 / 111。四舍五入会带来一两兆的误差,但总量守恒,且每一档都能用「权重 ÷ 总权重 × 480」手算复现。这比给每类设备写死一个带宽值更耐改:以后加第七件器械,只要给它一个权重,分舱逻辑一行不用动。


健康判定同样是纯函数,把「电量」这一个连续值折成三档语义:低于 20% 是低压告警,低于 50% 是巡航,其余是满帆;有线设备直接返回 wired,不参与电量分级。渲染层拿到的是 low / cruise / full / wired 四个语义值,具体显示成什么颜色、什么灯,完全交给 CSS。状态与表现分离之后,换一套配色不需要改任何 JS。
还有两个容易被忽略的细节。其一,离泊返回的是新的登记表,而不是原地 splice,这样每一次操作都能被快照、被回放、被单测断言;其二,重复靠泊同一件器械会被直接拒绝,返回原登记表,调用方据此决定要不要写日志。状态机宁可少做一次,也不进入「同一件设备在泊位里出现两次」的脏状态。
六、系统脉搏:电量档位驱动能力矩阵
右栏需要额外说明:哪些数字来自真实调用,哪些只是演示数据。
真的部分有两块。第一块是右上角的运行时徽标,来自主进程真实调用:
// app/main-utils.cjs —— 运行时信息由引擎自报
function getRuntimeInfo(app, processObj) {
return {
app: app?.getName() || 'CogBay',
version: app?.getVersion() || '0.0.0',
platform: processObj?.platform, // 鸿蒙 PC 上为 'openharmony'
arch: processObj?.arch, // arm64
node: processObj?.versions?.node || '',
host: os.hostname()
};
}
第二块是能力矩阵的联动规则。电量档位不是装饰性的文字,它会真实改变能力可用性:
// app/gearbay.mjs —— 电量 → 能耗档位
export function powerPlan(battery, charging) {
const level = Number(battery);
if (!Number.isFinite(level)) {
return { id: 'balanced', label: '均衡', reason: '电量未知,默认均衡' };
}
if (charging) {
return { id: 'performance', label: '全速', reason: '外接供电,放开性能' };
}
if (level < 25) {
return { id: 'eco', label: '省航', reason: `电量 ${Math.round(level)}%,进入省航` };
}
if (level < 60) {
return { id: 'balanced', label: '均衡', reason: `电量 ${Math.round(level)}%,均衡巡航` };
}
return { id: 'performance', label: '全速', reason: `电量 ${Math.round(level)}%,可全速运转` };
}
档位确定之后,六项能力按平台与档位两个维度给出可用性:
// app/gearbay.mjs —— 平台 × 档位的能力矩阵
export function capabilityMatrix(platform, planId) {
const ohos = platform === 'ohos' || platform === 'openharmony';
const eco = planId === 'eco';
return [
{ id: 'fs', name: '文件收发', ok: true, note: ohos ? '应用沙箱 + 用户目录授权' : '浏览器预览为模拟' },
{ id: 'pasteboard', name: '剪贴板桥', ok: true, note: ohos ? '系统剪贴板读写' : '浏览器预览为模拟' },
{ id: 'battery', name: '电量哨兵', ok: true, note: ohos ? 'batteryInfo 系统接口' : '浏览器预览为模拟' },
{ id: 'peripheral', name: '外设泊位', ok: true, note: ohos ? 'deviceManager 设备管理' : '浏览器预览为模拟' },
{ id: 'notify', name: '湾务通知', ok: !eco, note: eco ? '省航档位下静默' : 'notification 模板消息' },
{ id: 'vibrate', name: '舵机震感', ok: ohos && !eco, note: ohos ? (eco ? '省航档位下关闭' : 'startVibration 短震') : '仅鸿蒙真机可用' }
];
}
矩阵里有三种状态,含义各不相同:ok: true 表示这条链路在当前平台可用;ok: false 且文案是「省航档位下静默」的,属于主动策略——电量低时关掉通知与震动,是产品决策,不是能力缺失;而「仅鸿蒙真机可用」与「浏览器预览为模拟」则是平台降级,在浏览器里打开时必然出现。把三种状态混成一句「不可用」,用户就分不清是手机没电还是功能没做。

需要诚实说明的是:电量读数与耗电模拟是本地演示数据,用来验证「档位切换 → 能力联动」这条逻辑;batteryInfo、deviceManager、系统剪贴板、notification 是鸿蒙 PC 侧预留的真实接入点,矩阵里的文案已经按真实接口名写好。外设泊位目前是状态机模拟,没有真正枚举硬件。这种「真实骨架 + 可替换数据源」的拆法,可以先用纯逻辑把交互与边界跑通,再逐项替换成真实能力;反过来先接硬件,一个权限没放行就可能卡住整条链路,连界面都看不到。
七、六个只在鸿蒙 PC 出现的构建与安装问题
下面这些问题有个共同特征:真正的原因往往藏在报错信息的另一头。CogBay 在这个跨平台框架的工程里把它们逐个写进了构建脚本,而不是留在文档里靠人记。
| 现象 | 真实原因 | 处理 |
|---|---|---|
00308018 Unknown Error / CompileArkTS 失败 | 工程搬迁后 oh_modules 里的符号链接仍指向旧绝对路径 | hap:init 遍历重建链接,hap:relink 兜底并清缓存 |
| 窗口顶部出现两条菜单 | 鸿蒙 PC 窗口自带系统菜单区 | Menu.setApplicationMenu(null) 并纳入静态检查 |
装包报 9568332 install sign info inconsistent | 同包名已装应用的签名身份不同 | 先卸载同包名旧版;包名以 .p7b 材料为准 |
装包报 9568289 grant request permissions failed | profile 的 acls 为空,受限权限未授权 | 在 AGC 为应用申请权限,让 profile 带上 ACL |
构建报 10311002 OhmUrl 相关失败 | 壳工程搬迁后链接与缓存不一致 | 执行 npm run hap:relink 后重新构建 |
只产出 *-unsigned.hap | 工程缺 signingConfigs,构建「成功」却装不上 | 先 hap:sign,从 .p7b 反解包名并回写配置 |
本地 npm i -D electron 正常,装到机器上对不上 | npm 版 Electron 在 OpenHarmony 上没有对应二进制 | 不装 npm 版,业务代码交给 HAP 内的 .so 执行 |
| 首次安装等待很久 | HAP 约 210 MB,引擎占绝大部分 | 耐心等待,别反复重试制造签名/版本冲突 |
前两条是「删了照样能跑、但会在某个时刻炸掉」的典型。符号链接的问题尤其隐蔽:报错在 ArkTS 编译阶段,真正的原因却在工程目录搬家时留下的绝对路径。hap-init.mjs 在拷贝官方壳工程之后会递归遍历 oh_modules,把仍指向源目录的链接改写到本工程;hap-relink.mjs 则专门处理外部 ohos_hap 前缀,并顺手清掉 .hvigor 与失败的 build/ 中间产物,让 hvigor 重新生成。脚本里还专门拦了一种情况:源 ohos_hap 副本如果残留了本机 DevEco 写入的 signingConfigs 密文,直接拒绝初始化,否则别人的签名材料会被悄悄带进你的工程。
签名这一步也值得单说。鸿蒙的包名是被签名 profile 锁死的,写死一个包名会在换签名材料时集体失效。CogBay 的 hap-sign.mjs 从 .p7b 里反解出 bundle-name,再回写 hap.config.json 与 AppScope/app.json5,所以截图里的徽标与安装命令用的 com.mosaic.windowlab 来自同一份材料,而不是手抄的字符串。构建、安装、启动分别是 hvigorw.js assembleHap、hdc install -r、aa start -a EntryAbility -b <bundleName>,全部由 npm 脚本串起来。
安全基线也没有停留在文档里,而是直接进了检查脚本:
// scripts/check.mjs(节选)
if (!html.includes("script-src 'self'") || !html.includes("object-src 'none'")) {
throw new Error('渲染进程 CSP 不符合安全基线');
}
for (const requiredOption of ['contextIsolation: true', 'nodeIntegration: false', 'sandbox: false', 'webSecurity: true']) {
if (!mainProcess.includes(requiredOption)) {
throw new Error(`主进程缺少安全配置:${requiredOption}`);
}
}
if (!mainProcess.includes('Menu.setApplicationMenu(null)')) {
throw new Error('主进程缺少 Menu.setApplicationMenu(null)(鸿蒙系统菜单区与应用菜单会叠加)');
}
if (!mainProcess.includes("'openharmony'") || !mainProcess.includes("'ohos'")) {
throw new Error('主进程需同时识别 openharmony 与 ohos 两种 platform 返回值');
}
if (rootPackage.devDependencies?.electron) {
throw new Error('不应依赖 npm 标准 Electron:OpenHarmony 无官方二进制');
}
这五条盯的都是「删掉之后短期内看不出问题」的配置:CSP 放宽到 unsafe-inline 时页面照样显示,nodeIntegration 打开时开发更顺手,菜单被恢复时桌面端也没事,平台判定写单值时只有鸿蒙 PC 会崩,装了 npm 版 Electron 时本地也不会立刻失败。这类问题在评审时几乎不会被注意到,只有写成门禁,才能一次拦住、长期生效。
八、这套骨架为什么值得复用
三条链路并排放在一起,骨架立刻重合:
用户动作 → 窄门(preload 暴露的极少数方法) → 主进程闸口(鉴权 / 限流 / 夹取)
→ 纯函数(分类、状态机、档位) → 不可变状态 → 渲染
文件关心的字段是名字与体积,外设关心类型与权重,系统能力关心 id 与档位。三者的字段与阈值都不同,但校验发生在哪、失败怎么表达、状态怎么更新,答案是一样的。这也是为什么 CogBay 能用七百多行核心 JS 撑起三块功能:抽象对了,重复的部分自然消失。

对 Electron 这个跨平台框架来说,这套结构还有一个额外好处:gearbay.mjs 与 main-utils.cjs 都不 import electron,也都不碰 DOM,所以它们既能被 Electron 主进程用、也能被渲染进程 import、还能被 Node 直接跑测试,甚至丢进浏览器预览模式里跑。真正跨平台的不是界面,而是这些与平台无关的规则;界面和框架 API 是最容易替换的两层,规则不是。
还需要交代一条边界。本文的 CogBay 里,文件链路的选择、拖拽与调度是真的(真实 File 对象、真实排序过滤、真实去重与估算),运行时信息是真的(主进程现取平台与架构),外设泊位是状态机模拟(没有真正枚举硬件),电量与系统能力读数是演示数据(结构已对齐 batteryInfo、deviceManager、剪贴板、notification 等真实接入点)。把一个鸿蒙 PC 应用拆成「真实骨架 + 可替换数据源」,可以先用纯逻辑把交互和边界跑通,再逐项替换成真实能力;这条路径比「先接硬件、再补界面」更稳,也更适合在鸿蒙 PC 上快速验证一个想法。
附录:环境与命令速查
本文验证环境:鸿蒙 PC 真机(2in1 形态),系统 OpenHarmony 7.0,命令行工具集 hmos-clt 1.0.0(hdc / hvigor / ohpm / node 全部内置),Electron 分支 v40.0.1,工程包名 com.mosaic.windowlab,模块 electron,Ability EntryAbility。
# 1) 环境体检:Node、hdc、ohpm、hvigorw.js、SDK、签名材料、预编译包
npm run doctor
# 2) 静态检查 + 近二十条单测 + dist 构建
npm run verify
# 3) 首次:从官方 ohos_hap 初始化壳工程(源工程需先剥离 signingConfigs)
PANEVERSE_HAP_SDK=/path/to/libelectron/ohos_hap npm run hap:init
npm run hap:sign -- --prefix Mosaic
# 4) 构建 → 安装 → 启动
npm run hap:build
npm run hap:install
npm run hap:start
# 5) 若构建报 10311002 OhmUrl 失败,先重链再重试
npm run hap:relink && npm run hap:build
# 6) 真机截图取证
hdc shell "snapshot_display -f /data/local/tmp/cogbay.jpeg"
hdc file recv /data/local/tmp/cogbay.jpeg ./cogbay.jpeg
工程结构:
CogBay/
├── hap.config.json # 包名 / 模块名 / 运行时目录,单一配置源
├── app/ # Electron 业务代码(跨平台部分)
│ ├── main.js # 主进程:窗口、IPC、菜单、权限
│ ├── preload.js # 窄门:只暴露 getRuntime 与 calibratePointer
│ ├── main-utils.cjs # 坐标夹取、入口同源校验、运行时信息(纯函数)
│ ├── gearbay.mjs # 文件 / 外设 / 系统能力调度引擎(纯函数)
│ ├── renderer.mjs # 编排:事件 → 窄门 → 纯函数 → 渲染
│ └── index.html/styles.css
├── scripts/ # init / relink / sync / sign / build / install / start / check / doctor
├── tests/ # gearbay 与 main-utils 单测,node --test 直跑
└── hap/ # 官方壳工程 + libelectron.so + libadapter.so(构建生成)
项目已托管在 AtomGit 的开源鸿蒙 PC 社区组织下(https://atomgit.com/OpenHarmonyPCDeveloper),可对照源码阅读。
延伸阅读(均在 AtomGit):
https://atomgit.com/CPF-Electron/Electron—— 基于 Electron 的鸿蒙化适配项目,覆盖环境配置、源码编译、HAP 构建与权限定制,可与本文的 HAP 工程结构对照看;https://atomgit.com/OpenHarmonyPCDeveloper—— 开源鸿蒙 PC 社区项目入口,适合找同类的鸿蒙 PC 应用样本。
如果你也准备在鸿蒙 PC 上用 Electron 这个跨平台框架做应用,建议先做一件事:把「哪些能力必须过主进程」画成一张三层图贴在仓库 README 上。图画清楚之后,代码结构基本就自动长对了;剩下的,只是把每一层的输入夹到合法范围,把每一条规则写成能单独跑起来的纯函数。
更多推荐
所有评论(0)