Electron 跨平台框架实战:在鸿蒙 PC 用 CogBay 齿湾调度文件、外设与系统能力

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

前言

桌面应用的功能列表可以列得很长,但真正需要向操作系统要的东西并不多:用户愿意交出的文件、插上来就能用的外设、以及电量与剪贴板这类系统级状态。剩下的工作,是把这三类能力组织成用户愿意每天打开的界面。

这篇文章的样本叫 CogBay(齿湾),是一个在鸿蒙 PC 上使用 Electron 跨平台框架 开发的鸿蒙 PC 应用。它把文件当作进湾的货件、把外设当作泊位上的器械、把电量与系统能力当作仪表盘上的脉搏,用一张三栏作业台把三类调用收进同一个工作区:左栏「外设泊位」,中栏「文件枢纽台」,右栏「系统脉搏」。整套业务代码不依赖任何 npm 版 Electron 二进制,最终以 HAP 应用包的形式跑在鸿蒙 PC 桌面上。

「Electron 能跑在鸿蒙 PC 上」已经被验证过很多次,这里不再复述,而是想把三件更具体的事讲透:

  1. 在鸿蒙 PC 上,Electron 应用的能力边界画在哪一层——哪些调用必须经过主进程,哪些可以留在渲染层;
  2. 文件、外设、系统能力这三条链路,如何被拆成可测试的纯函数,而不是散成一堆事件回调;
  3. 这条链路上几个只在鸿蒙 PC 上出现、在 Windows / macOS 上永远遇不到的坑。

关键词:鸿蒙 PC、Electron、跨平台框架、文件系统调用、外设管理、系统能力调用、HAP 打包、IPC 安全、AtomGit

CogBay 齿湾在鸿蒙 PC 真机运行:桌面底部 Dock、背后 DevEco Studio,前景三栏作业台已入湾 8 件文件、在泊 4 件器械

上图就是最终形态。鸿蒙 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.soElectron / 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,以及右栏「能力矩阵」中对浏览器预览模式的降级说明:

CogBay 空载状态:左外设泊位、中文件枢纽台、右系统脉搏,右上角运行时徽标回显 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」手算复现。这比给每类设备写死一个带宽值更耐改:以后加第七件器械,只要给它一个权重,分舱逻辑一行不用动。

CogBay 单件器械靠泊:航标键盘独占 480 Mbps,日志记录靠泊成功与带宽重新分舱

CogBay 四件器械在泊:航标键盘 74、操舵手柄 111、钤印打印机 185、听浪耳机 111 Mbps

健康判定同样是纯函数,把「电量」这一个连续值折成三档语义:低于 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 且文案是「省航档位下静默」的,属于主动策略——电量低时关掉通知与震动,是产品决策,不是能力缺失;而「仅鸿蒙真机可用」与「浏览器预览为模拟」则是平台降级,在浏览器里打开时必然出现。把三种状态混成一句「不可用」,用户就分不清是手机没电还是功能没做。

CogBay 三件器械在泊时的能力矩阵与湾务日志:通知与震感随档位联动,日志按文件、泊位、能耗、启运四类留痕

需要诚实说明的是:电量读数与耗电模拟是本地演示数据,用来验证「档位切换 → 能力联动」这条逻辑;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 failedprofile 的 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 撑起三块功能:抽象对了,重复的部分自然消失。

CogBay 两件器械在泊:航标键盘 192 Mbps 与操舵手柄 288 Mbps,总带宽仍为 480 Mbps

对 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 上。图画清楚之后,代码结构基本就自动长对了;剩下的,只是把每一层的输入夹到合法范围,把每一条规则写成能单独跑起来的纯函数。

Logo

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

更多推荐