应用更新提醒、服务器告警、订单状态——鸿蒙把这些统一收进系统通知中心:横幅、锁屏、桌面角标、点击路由,全由系统接管。但 Electron 应用跑上鸿蒙之后,主进程的 Node.js 既摸不到 @ohos.notificationManager,也和 ArkTS 壳不在同一个运行时里。怎么把系统级推送封装成一个 Electron 可用的三方库、怎么用本地回环 TCP 桥打通「Node 进程 → ArkTS 壳 → Notification Kit」这条链。

示例仓库:https://atomgit.com/dijun_520/electron-push-ohos
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-Electron/Electron/tree/v40.1.0-openharmony
CPF-Electron 鸿蒙社区:https://atomgit.com/CPF-Electron


0. 环境与实测设备

项目版本
开发工具DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk)
系统 APIHarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0)
Electron桌面示例 electron 40.1.0(Chromium 144 / Node 24);鸿蒙端为 CPF-Electron v40 运行时(libelectron.so)
Node.js≥ 22.11.0
实测设备HarmonyOS 7 PC(MateBook Pro)

1. “发条通知而已,平台差异能有多大”

接到这个题的时候,我的朴素理解非常直接:推送嘛,就是 notificationManager.publish() 包一层。鸿蒙的通知 API 是 ArkTS 的,Electron 主进程是 Node 的,中间挂个桥不就完了?至于桥怎么挂,我一开始想得也很美:写个 Node-API addon,把 ArkTS 函数表注册进 Node——日历那篇就是这么干的。

这个理解撑了大概一小时。翻开鸿蒙 NDK 的 Notification C API 头文件,看到的是另一番景象:

// libohnotification.so 对外暴露的查询接口(ndk,节选)
OH_Notification_IsNotificationEnabled     // 查询通知使能
OH_Notification_GetSlotSettingByType      // 查询通道设置
// ——没有 publish。

NDK 只给"查",不给"发"。发布系统通知必须走 ArkTS 的 @ohos.notificationManager。更麻烦的是第二堵墙:harmonypc-electron 的主进程是独立进程(libelectron.so 里跑着 Node 24),ArkTS 壳跑在宿主 UIAbility 进程里——两个进程之间没有共享运行时,Node-API 的函数表根本注册不进去。想靠"一个 so 两头调"把桥做薄,路不通。

第三堵墙来自系统本身。通知不是"发出去就完":点通知要把用户带回应用并带上业务参数(wantAgent 路由)、通知使能是 user_grant 级别的系统裁决(可能被拒、可能被关)、Push Kit 的设备 token 需要 AGC 签名资质。每一项都有自己的一套错误码和时序。第一轮真机验证,桥两端握手全通、publish 调用原样到达 ArkTS,通知却没有出现:

11-13 18:49:08.926 51723 51723 E C01203/com.example.immersiveoverlays/Ans:
  [a92ab1eb24e2080 0 0]Property notificationContentType expected.

所以这个题目的边界很清楚:把鸿蒙系统级推送封装成 electron-push-ohos 三方库——纯 Node 侧定契约(API、错误码、事件流),ArkTS HAR 起桥接服务用 notificationManager 干真活,两边用同一个应用沙箱的回环 TCP 说 NDJSON;桌面端自动降级成 Electron 原生 Notification 的 mock 后端,业务代码零改动;真机上把"发布 → 通知栏 → 点击回传"验证到端到端全通。

拆下来是三件事:

  • 把 JS 侧的推送操作(probe / requestPermission / publish / cancel / getToken)翻译成 ArkTS 侧的 notificationManager 调用,并把系统的错误码与事件流原样带回;
  • 让桌面端在没有鸿蒙运行时的环境里跑同一条链路:Electron 原生 Notification 承担"发",click 回调承担"点击回传",mock 推送服务端模拟"服务端下发";
  • 在真机上验证发布、通知栏展示、点击回传三段链路,把每一个系统拒绝的原因如实带回业务层。

2. 效果展示

请添加图片描述

这是 macOS 上 npm start 跑出来的窗口。这里每一块都不是装饰:

  • 标题旁的徽标 desktop · mock 来自 electronPush.getCapability() 的返回——桌面没有鸿蒙运行时,engine=mock,库如实标注"你在看的是降级链路";
  • ① 的 已授权 ✅ 是 getPermission() 的结果,背后对应 ArkTS 侧的 isNotificationEnabled()(桌面上由 Electron 的通知权限状态代替);
  • ② 的表单字段 标题/正文/附加文本/通道/点击参数 与 publish() 的入参一一对应:slotType 翻译成 notificationManager.SlotType,点击参数 key/value 会变成通知点击回传时的 params;
  • ③ 的 mock 服务端监听 127.0.0.1:7788,POST /push 模拟"服务端下发"——真机上这条链路由 Push Kit 的 receiveDataMessage 承担。

拿到 Token 那一栏,桌面上的表现本身就是一次诚实的降级示范:

请添加图片描述

获取 Token 按钮下面直接显示 PUSH_ERR_PUSHKIT_UNAVAILABLE: Push Kit unavailable: requires AGC signing & pushService config(需 AGC 配置)——库不吞错误、不返回假 token,错误码本身就是 API 的一部分。下方的 ⑤ 事件日志里,published {"id":2}、published {"id":1} 两条记录对应两次真实发布,id 是库侧发的自增号,取消通知时用的就是它。

请添加图片描述

真机上的故事从通知栏开始。宿主 HAP 装上 TLR-AL00、aa start 拉起之后,从主机侧向设备里的 mock 服务端发一条推送:

# hdc 端口转发:主机 17788 → 设备 7788
hdc -t <序列号> fport tcp:17788 tcp:7788
curl --noproxy '*' -X POST http://127.0.0.1:17788/push \
  -H 'Content-Type: application/json' \
  -d '{"title":"真机推送验证","text":"electron-push-ohos TCP 桥端到端跑通"}'
# 返回 {"ok":true,"id":1}

下拉通知栏,通知就挂在那里:

请添加图片描述

这张截图值得逐条看:真机推送验证 / electron-push-ohos TCP 桥端到端跑通(刚刚)这条通知,是主机上的 curl → 设备内 mock 服务端 → Electron 主进程 → TCP 回环桥 → ArkTS notificationManager.publish() 一路递上来的。

换一条带 slotType: social 的推送再发一次,通知栏里的第二张 Electron 通知卡(真机横幅通知 / electron-push-ohos 前台横幅展示 · TCP 桥链路)挂在充电提醒和 App Market 更新之间——slotType 的差异在真实通知栏里肉眼可辨:

请添加图片描述

点击这条通知,链路最后一跳被真实触发。hilog 里的记录(tag=ElectronPush 与主进程事件流):

// 设备 hilog(tag=ElectronPush)
ElectronPush: push bridge listening on 127.0.0.1:47133
ElectronPush: electron main connected, peers=1
ElectronPush: call publish

// 主进程事件流(Node 侧 console)
[event] click: {"id":1,"label":"","params":{"pushId":"1",
  "ohos.params.launchReasonMessage":"ReasonMessage_Notification",
  "ohos.aafwk.param.callerBundleName":"com.ohos.sceneboard", ...}}

launchReasonMessage: ReasonMessage_Notification 是系统塞进 want 参数里的"拉起原因"——它证明这次启动确实是用户点了通知,而不是别的原因;pushId: "1" 是我们发布时塞进 wantAgent 的自定义参数,原样回到了 Node。

请添加图片描述

UI 上还有一条证据线。phone 形态的设备上 snapshot_display 截不到 Electron 窗口表面(坑八),但 uitest dumpLayout 能证明界面真的在渲染:

// 真机 uitest dumpLayout(节选)
Electron 鸿蒙推送中心 · electron-push-ohos [0,105][1084,2412]
File [0,105][96,180]
Edit [96,105][198,180]
View [198,105][315,180]
Window [315,105][486,180]
Help  [486,105][600,180]

主动交代边界,有三条:

  1. Push Kit 的系统级推送通道没有验证到端到端——receiveDataMessage 订阅依赖 AGC 签名配置,本文的调试包名没有推送权益,hilog 里是预期分支 push kit dataMessage not available, skipped。库把订阅逻辑全部写好,资质开通后无需改代码;
  2. phone 形态设备上 Electron 窗口的表面进不了 snapshot_display 截图(白屏),取证靠 dumpLayout 与事件日志双线并行;
  3. 测试包名 com.example.immersiveoverlays 与同系列其他示例共用,设备上出现过互相覆盖安装的情况(坑七),复现时先确认设备上装的是谁的包。

3. 原理:通知到底归谁管,桥为什么非是 TCP 不可

先给全文最重要的模型判断:通知是系统资产,点击是路由行为。 publish() 之后,这条通知的展示位置(横幅/锁屏/角标)、优先级(SlotType)、生死(tapDismissed / cancel)全由系统裁决;应用能做的只有两件事——把结构化内容递上去,以及声明"点它应该去哪"(wantAgent)。点击不是回调,是系统带着参数把你的 UIAbility 拉起来。

第二个判断:在 Electron 鸿蒙化里,进程边界决定桥的形态。 主进程 Node 和 ArkTS 壳是两个进程,没有共享运行时,Node-API 注册不进去;NDK 又只给查询不给发布。但两个进程同属一个应用、同一个 uid,回环网络栈是共享的——127.0.0.1 上的 TCP 连接两端都能开。于是公式变成了:

Electron 主进程(Node, net)→ 本地回环 TCP(NDJSON)→ ArkTS TCPSocketServer(HAR)→ notificationManager

把整条链路的接口和事件整理成表:

接口/事件方向载荷应用要回答什么
TCPSocketServer.listen({address:'127.0.0.1'})ArkTS → 系统端口号(47133 起依次探测)监听就绪,等主进程来连
{v,id,method,args}\nNode → ArkTSNDJSON 请求帧getCapability/requestPermission/getPermission/publish/cancel/cancelAll/getToken 之一
{v,id,ok,data|error}\nArkTS → NodeNDJSON 响应帧系统错误码 + message(原样回传)
{event,args}\nArkTS → NodeNDJSON 通知帧click / dataMessage / permissionChanged 事件流
isNotificationEnabled()应用 → 系统无通知使能与否
requestEnableNotification(ctx)应用 → 系统UIAbilityContext是否弹系统授权框、用户是否允许
publish(request)应用 → 系统NotificationRequest是否被 401 拒绝(字段强校验)
wantAgent.getWantAgent(info)应用 → 系统WantAgentInfo点击后拉起哪个 Ability、带什么参数

三个细节决定了后面所有的实现取舍:

  1. 错误码是系统的,不是库的。 publish 被拒时返回的 401 带着系统原文(第 5.3 节的两个 401 全部来自这条透传链),库的职责是包成 PushError 后一字不改地交给业务层——业务侧拿 err.message 就能直接对照官方错误码表排障。
  2. 点击的载体是 wantAgent,时序却是"发布时"。 publish() 的那一刻就要把 pushId 和业务参数封进 wantAgent,等用户点击时系统拉起 UIAbility 并把这些参数塞进 want.parameters——中间可能隔着几秒到几天,参数必须是自包含的。
  3. 事件有三类、三个来源。 click 来自宿主 Ability 的 onCreate/onNewWant,dataMessage 来自 Push Kit 订阅回调,permissionChanged 来自使能状态变化。三条线在 ArkTS 侧汇进 PushEventHub,走同一条 TCP 广播出去,Node 侧归一成 EventEmitter 的三个事件。

4. 工程怎么搭

这次整理最关键的变化,是把"能跑"变成"能复用":纯 Node 核心、ArkTS HAR、示例工程三件事拆进三个目录,互相只通过公共边界说话。

electron-push-ohos/
├── package.json                  # main: dist/index.js,test 一键跑三套验证
├── src/                          # 纯 Node 核心(零 Electron 依赖,可单测)
│   ├── types.ts                  # 与 ArkTS 契约一一对应的类型
│   ├── core.ts                   # PushError + PushErrorCode(错误码即 API)
│   ├── index.ts                  # electronPush 单例:后端选择 + 错误归一化
│   ├── native.ts                 # 桥加载层:openharmony → TCP 桥,桌面 → null
│   ├── tcpBridge.ts              # TCP 回环桥:端口探测/NDJSON/超时/重连
│   ├── ohosBackend.ts            # method 转发 + 事件分发(真后端)
│   └── mockBackend.ts            # Electron 原生 Notification(桌面后端)
├── harmony/push/                 # ArkTS HAR(源码方式参与宿主编译)
│   └── src/main/ets/
│       ├── PushBridgeServer.ets  # TCPSocketServer:监听/分帧/分发/广播
│       ├── PushManager.ets       # notificationManager 发布/取消/权限/wantAgent
│       ├── PushEventHub.ets      # click/dataMessage/permissionChanged 回传
│       └── PushDataAdapter.ets   # 宿主一行接入(install / onNewWant)
├── example/                      # 推送中心演示工程(本文桌面截图来源)
│   ├── main.js / preload.js / renderer/
│   ├── server/mock-push-server.js  # HTTP 模拟服务端下发
│   ├── electron-app/             # 真机 app 包(依赖本库 file:../..)
│   └── ohos-host/                # harmonypc-electron 宿主工程(HAP 打包)
├── scripts/build-device.sh       # 一键:tsc → 依赖 → resfile 同步 → assembleHap → hdc 安装
└── test/                         # mock 冒烟 + headless e2e(8 项断言)+ TCP 桥回环

三条边界:src/ 不带任何 UI 与 Electron 依赖,单测跑在纯 Node 上;harmony/push/ 不感知业务,只认 NDJSON 协议与 JSON 参数;example/ 只走公共 API。

业务侧最小接入(主进程 12 行):

// Electron 主进程 - 三步:听事件 → 探能力 → 发通知
const { electronPush } = require('electron-push-ohos');

electronPush.on('click', (p) => goDetail(p.id, p.params));   // 点击回传
electronPush.on('dataMessage', (m) => syncOrder(m.data));    // Push Kit 系统级推送

const cap = await electronPush.getCapability();  // { platform, engine, ... }
await electronPush.requestPermission();          // 首次弹系统授权框
await electronPush.publish({
  title: '服务器公告', text: '磁盘水位 85%,请关注',
  slotType: 'service', clickParams: { target: 'ops-dashboard' },
});

鸿蒙宿主侧两行接线:

// 宿主页面 aboutToAppear:启动 TCP 桥 + 订阅 Push Kit
PushDataAdapter.install(getContext(this) as common.Context);

// 宿主 EntryAbility:通知点击冷/热启动都走这里
onNewWant(want: Want, _: AbilityConstant.LaunchParam): void {
  PushDataAdapter.onNewWant(want.parameters as Record<string, Object>);
}

通道协议只有一种帧格式——NDJSON,一行一个 JSON:

{"v":1,"id":7,"method":"publish","args":"{\"title\":\"真机推送验证\",\"text\":\"electron-push-ohos TCP 桥端到端跑通\",\"slotType\":\"service\"}"}
{"v":1,"id":7,"ok":true,"data":"{\"id\":1}"}
{"event":"click","args":"{\"id\":1,\"label\":\"\",\"params\":{\"pushId\":\"1\"}}"}

注意请求的 args 是字符串化的 JSON——ArkTS 侧收到后一次 JSON.parse 还原成 Record<string, Object>,避免帧内嵌套对象在严格模式下的类型推断问题。

两个容易被忽略的窗口期:

  1. 懒连接的首调竞态。 Node 侧的桥是懒连接:第一次 call 时才开始探测端口。如果 ArkTS 侧的 server 还没 listen,四个端口全部探测失败会抛 push bridge not reachable——所以宿主侧把 PushBridgeServer.start() 放在页面 aboutToAppear,比 Electron 主进程加载 app 更早;Node 侧探测每口 600ms 超时,四次失败后 800ms 退避重连,宁可让调用方多等一秒,不在启动时序上赌运气。
  2. 断线不能悬挂 Promise。 宿主 Ability 被杀、设备休眠都会断开 TCP。Node 侧对断线时的 pending 请求立即 reject(不悬挂),随后自动退避重连;重连后不重放旧请求——publish 重放会发出两条通知,把重试语义还给业务层,库只保证不吞事件、不悬挂调用。

5. 把代码讲透

5.1 传输层:四个端口挨个试,15 秒超时是底线

// src/tcpBridge.ts - tryConnect()(节选)
private tryConnect(port: number, timeoutMs = 600): Promise<boolean> {
  return new Promise((resolve) => {
    const socket = net.createConnection({ host: '127.0.0.1', port });
    let settled = false;
    const done = (ok: boolean) => {
      if (settled) return;
      settled = true;
      if (!ok) { socket.removeAllListeners(); socket.destroy(); }
      resolve(ok);
    };
    socket.setNoDelay(true);
    socket.setTimeout(timeoutMs, () => done(false));
    socket.once('connect', () => { socket.setTimeout(0); this.attach(socket); done(true); });
    socket.once('error', () => done(false));
  });
}

// src/tcpBridge.ts - call()(节选)
const timer = setTimeout(() => {
  this.pending.delete(id);
  reject(new Error(`push bridge timeout: ${method}`));
}, 15000);

三个细节值得单独说:

第一,探测失败要"干净地"失败。 每个端口 600ms 探测超时,失败就把监听器拆干净、socket 销毁,再试下一个。没有这个 removeAllListeners + destroy。

第二,任何 RPC 都不许无限等。 ArkTS 侧偶尔不回调(系统忙、连接刚断),客户端把所有请求兜在 15 秒里,超时即拒绝并清掉 pending 表。

第三,分帧在两端各实现一次,规则完全一致。 Node 侧 LineDecoder 按 \n 切帧、trim 空行、坏帧直接丢弃;ArkTS 侧用 util.TextDecoder(保持多字节状态)+ 同样的 indexOf 循环。

5.2 点击回传:wantAgent 的三个编译期陷阱

// harmony/push/src/main/ets/PushManager.ets - publish()(节选)
const want: Want = {
  deviceId: '',
  bundleName: uiCtx.abilityInfo.bundleName,
  abilityName: uiCtx.abilityInfo.name,
  parameters: params,                        // pushId + clickParams 全在这里
};
const info: wantAgent.WantAgentInfo = {
  wants: [want],                             // ← 是 wants,复数!
  operationType: wantAgent.OperationType.START_ABILITY,
  requestCode: 0,
  wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG],
};
agent = await wantAgent.getWantAgent(info);  // ← 是 getWantAgent,不是 getAgent

三个细节值得单独说:

第一,字段名是 wants,复数。 第一版照着记忆写 want: want,编译器给了一整屏的类型不匹配。WantAgentInfo 的语义是"一组候选拉起目标",绝大多数场景只放一个,但它仍是数组。

第二,abilityInfo 不在 Context 上,在 UIAbilityContext 上。 Context.abilityInfo 直接编译报错,得先 as common.UIAbilityContext 再取 abilityInfo.bundleName / abilityInfo.name——所以 PushManager.init(context) 要求宿主传入 Ability 上下文,而不是随便一个 getContext(this) 的 Context。

第三,发布时构造、点击时兑现。 wantAgent 在 publish() 里构造一次,封装进 NotificationRequest.wantAgent;用户可能几天后才点。所以参数必须自包含:pushId 用于定位是哪条通知,clickParams 原样透传业务参数。

5.3 系统强校验:API 26 上的两个 401

// harmony/push/src/main/ets/PushManager.ets - publish()(节选)
const normal: notificationManager.NotificationContent = {
  // API 11 起 contentType 已废弃,真机(API 26)要求 notificationContentType
  notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
  normal: {
    title: String(args['title'] ?? ''),
    text: String(args['text'] ?? ''),
    // additionalText 必须是 string(传 undefined 会 401),缺省给空串
    additionalText: args['additionalText'] !== undefined && args['additionalText'] !== null
      ? String(args['additionalText']) : '',
  },
};

真机上第一轮发布,桥两端的握手、调用、回传全通,但通知没有出现。Node 侧收到的是系统的原文:

{"error":"PUSH_ERR_PUBLISH_FAILED","message":"401 Invalid parameter Incorrect parameter types. The type of additionalText must be string."}

hilog 里紧跟着另一条:

11-13 18:49:08.926 51723 51723 E C01203/com.example.immersiveoverlays/Ans:
  [a92ab1eb24e2080 0 0]Property notificationContentType expected.

三个细节值得单独说:

第一,contentType 已废弃,新字段叫 notificationContentType。 旧文档和老示例全是 contentType: notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,在 API 26 上系统直接报 Property notificationContentType expected。

第二,additionalText 不能是 undefined。 JS 习惯里"可选字段不传"就是 undefined,ArkTS 侧把这个 undefined 塞进 NotificationContent.normal,系统报"参数类型必须是 string"。修复是一行三元表达式:有值转 string,没值给空串。

第三,两个 401 是串行出现的。 修掉 notificationContentType 之后才轮到 additionalText 报错——系统校验是逐字段进行的,一次只报第一个错。这类"强校验型 Kit"的适配没有捷径,就是"报一个修一个"的循环,把每一轮修复都沉淀进适配器,业务侧永远写自己习惯的形状。

5.4 事件回传:三跳把一次点击带回 EventEmitter

// harmony/push/src/main/ets/PushEventHub.ets - notifyClick()(节选)
static notifyClick(wantParameters: Record<string, Object> | undefined): void {
  const payload = new ClickEventPayload();
  if (wantParameters != null) {
    payload.id = Number(wantParameters['pushId'] ?? 0);
    payload.label = String(wantParameters['pushLabel'] ?? '');
    payload.params = wantParameters;
  }
  PushEventHub.emitToNode('click', payload);   // → PushBridgeServer.emitEvent 广播
}

三个细节值得单独说:

第一,三跳各有一个职责。 第一跳在宿主 EntryAbility:冷启动是 onCreate 里的 want.parameters,热启动是 onNewWant——两条路都汇到 PushDataAdapter.onNewWant();第二跳在 PushEventHub:从 want 参数里剥出 pushId/pushLabel,连同完整的 params 打包;第三跳在 PushBridgeServer:把事件广播给所有已连接的 peer,Node 侧 tcpBridge.dispatch() 按 event 字段路由到 EventEmitter。

第二,pushService.on 的签名在 SDK 间有差异。 subscribeDataMessage() 里给 Push Kit 挂回调时,部分 SDK 版本编译器报 Expected 3 arguments, but got 2——所以订阅用 ESObject 动态调用包在 try/catch 里,不可用就静默跳过并打日志(真机 hilog:push kit dataMessage not available, skipped)。

第三,无连接时事件不缓存、不重放。 emitToNode() 在没有 peer 时直接丢弃——如果 Node 侧断线期间用户点了通知,click 事件不会在重连后补发。

5.5 降级与契约:mock 后端不是"另一套代码"

// src/index.ts - getBackend()(节选)
const bridge = loadNativeBridge();
if (bridge) {
  backend = createOhosBackend(bridge, handlers);
} else {
  if ((process.platform as string) === 'openharmony') {
    throw new PushError(PushErrorCode.NOT_SUPPORTED,
      'openharmony detected but native bridge unavailable');
  }
  backend = createMockBackend(handlers);
}

三个细节值得单独说:

第一,降级有明确的判据和底线。 桌面(macOS/Windows/Linux)自动降级 mock;但 process.platform === 'openharmony' 而桥不可用时显式抛错。

第二,mock 后端语义对齐真后端。 桌面 mock 用 Electron 原生 Notification 承担发布,click 回调承担点击事件,getToken() 按契约抛 PUSH_ERR_PUSHKIT_UNAVAILABLE——连"Token 在桌面上不可用"这条语义都是真的。

第三,错误码是一等 API。 所有后端错误在 wrapError() 归一成 PushError,err.code 是六个稳定枚举(PUSH_ERR_NOT_SUPPORTED / PERMISSION_DENIED / PUSHKIT_UNAVAILABLE / NATIVE_BRIDGE_FAILED / PUBLISH_FAILED / CANCEL_FAILED),err.message 保留系统原文。*

6. 踩坑与经验

坑一:rsync 一条 exclude,真机主进程静默退出。 第一轮真机部署,HAP 装上了、ArkTS 桥起在 47133,但 Electron 窗口不出现、7788 无监听、hilog 里没有任何 Node 侧日志,进程最后 exit with code:0——静默退出,连个像样的报错都没有。一开始以为运行时加载路径不对,后来才反应过来:打包脚本同步 app 目录时的 --exclude 'dist' 把 node_modules/electron-push-ohos/dist 一起排除了,主进程 require('electron-push-ohos') 第一行就挂:

# HAP 内依赖包内容对比(unzip -l electron-default-signed.hap)
node_modules/electron-push-ohos/package.json   # 在
node_modules/electron-push-ohos/dist/index.js  # 不存在!

修复是把排除规则锚定到应用根:--exclude '/dist',并在脚本里强制先跑 tsc 再同步。

坑二:ArkTS 严格模式第一轮 19 个编译错。 把 JS 习惯直接搬进 .ets,hvigor 第一轮给出 19 个 ArkTS Compiler Error,主力是三条规则:

Error Message: Object literal must correspond to some explicitly declared class or
  interface (arkts-no-untyped-obj-literals)
Error Message: Object literals cannot be used as type declarations
  (arkts-no-obj-literals-as-types)
Error Message: Property 'getAgent' does not exist on type 'typeof wantAgent'.

对象字面量必须对应显式声明的类,响应体全改成 WireResponse/WireError/OkObj/IdObj/TokenObj 这类一层壳;wantAgent.getAgent 改成 getWantAgent;WantAgentInfo 的字段是 wants(复数)。

坑三:401 双连击,一次只报一个错。 5.3 节已经展开:Property notificationContentType expected 和 The type of additionalText must be string 前后脚出现。

坑四:通知权限 1600004,授权框只有一次机会。 自动演示在启动 4 秒后调 requestPermission() → publish(),真机上发布被拒:

{"error":"PUSH_ERR_PUBLISH_FAILED","message":"1600004 Notification disabled"}

手动导航到 Electron(版本 1.0.1)的通知管理页,进来时"允许通知"确实关着——和 hilog 里的 1600004 互相印证:

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

打开开关(顺手把"横幅通知"提醒方式也勾上),之后同一台设备的 POST /push 立刻从 1600004 变成 {"ok":true,"id":2}:

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

这张设置页同时解释了另一件事:slotType 不是摆设——系统按通道维度渲染提醒方式、铃声与振动,库把 slotType 参数翻译成 SlotType.SOCIAL/CONTENT/...,用户在系统里看到的就是对应通道的开关。

坑五:调试 profile 的 ACL 白名单是空的,装包直接失败。 给宿主加权限时踩的:

error: failed to install bundle. code:9568289 error:
  install failed due to grant request permissions failed.
  PermissionName: ohos.permission.READ_WRITE_DESKTOP_DIRECTORY

调试签名的 profile 里 allowed-acls 是空数组,任何受限权限都会让安装直接失败——不是运行时报错,是装都装不上。逐个删掉 requestPermissions 里的受限项(它们都是可选增强能力)后安装通过。

坑六:HAR 工程缺 build-profile.json5,hvigor 第一时间摔在配置上。 把 ArkTS 源码拷进宿主的 electron_push/ 模块后,hvigor 报:

Error Message: Can not find build config file build-profile.json5 at 'electron_push'.

三方库以源码 HAR 形式参与宿主编译时,每个模块都得是一套完整的 hvigor 工程形状:oh-package.json5、build-profile.json5(apiType: stageMode)、hvigorfile.ts、module.json5 一个不能少。


7. 现在怎么用:从 三方库 到依赖

业务侧接入三步走:

# 1. 安装三方库(发布后)
npm install electron-push-ohos

# 2. 主进程直接用
#    const { electronPush } = require('electron-push-ohos')

# 3. 桌面开发调试
cd example && npm install && npm start
# mock 服务端已监听 127.0.0.1:7788,POST /push 即可下发

鸿蒙端在 Electron-OHOS 宿主工程里补两件事:

# 1. 源码 HAR 进宿主(electron_push/ 模块),oh-package.json5 声明依赖
#    "electron-ohos-push": "file:../electron_push"

# 2. 一键构建 + 安装真机
scripts/build-device.sh --install
#    完成:tsc 编译 → 示例依赖(--install-links 落盘)→ rsync 进宿主 resfile
#          → hvigor assembleHap → hdc install
hdc -t <序列号> shell aa start -a EntryAbility -b <bundleName>

总结:

本文围绕 CPF-Electron 鸿蒙环境下的系统通知方案 electron-push-ohos 展开,核心痛点是 Electron 的 Node 主进程与 ArkTS 宿主分属独立进程,NDK 仅支持通知查询、无法直接发布通知,Node-API 跨运行时桥接方案行不通。

方案采用本地回环 TCP + NDJSON构建双向桥:ArkTS HAR 侧起 TCP 服务,封装 notificationManager、wantAgent 能力,负责通知发布、权限校验、点击事件采集;Node 主进程作为客户端发起调用,统一抽象出发布、取消、权限查询、事件监听接口,桌面端自动降级到 Electron 原生通知 mock 实现,业务代码无需改动。

整体工程分层解耦,Node 核心、ArkTS 桥接层、示例应用相互隔离,定义了一套稳定的 RPC 协议与事件流,支持端口自动探测、调用超时、断线重连,点击参数在发布时封入 wantAgent,实现冷/热启动均可回传业务参数。真机适配 API 26 时存在强字段校验,notificationContentType、additionalText 等字段容易触发 401 参数错误;同时存在权限 1600004、ArkTS 严格模式编译、rsync 打包排除、HAR 模块配置缺失、调试 ACL 权限受限等一系列典型坑点。

Logo

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

更多推荐