鸿蒙 Electron 推送避坑实战:Node 主进程与 ArkTS 壳进程隔离,TCP 桥对接 Notification Kit,通知栏展示和点击回调
应用更新提醒、服务器告警、订单状态——鸿蒙把这些统一收进系统通知中心:横幅、锁屏、桌面角标、点击路由,全由系统接管。但 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) |
| 系统 API | HarmonyOS 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]
主动交代边界,有三条:
- Push Kit 的系统级推送通道没有验证到端到端——
receiveDataMessage订阅依赖 AGC 签名配置,本文的调试包名没有推送权益,hilog 里是预期分支push kit dataMessage not available, skipped。库把订阅逻辑全部写好,资质开通后无需改代码; - phone 形态设备上 Electron 窗口的表面进不了
snapshot_display截图(白屏),取证靠dumpLayout与事件日志双线并行; - 测试包名
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}\n | Node → ArkTS | NDJSON 请求帧 | getCapability/requestPermission/getPermission/publish/cancel/cancelAll/getToken 之一 |
{v,id,ok,data|error}\n | ArkTS → Node | NDJSON 响应帧 | 系统错误码 + message(原样回传) |
{event,args}\n | ArkTS → Node | NDJSON 通知帧 | click / dataMessage / permissionChanged 事件流 |
isNotificationEnabled() | 应用 → 系统 | 无 | 通知使能与否 |
requestEnableNotification(ctx) | 应用 → 系统 | UIAbilityContext | 是否弹系统授权框、用户是否允许 |
publish(request) | 应用 → 系统 | NotificationRequest | 是否被 401 拒绝(字段强校验) |
wantAgent.getWantAgent(info) | 应用 → 系统 | WantAgentInfo | 点击后拉起哪个 Ability、带什么参数 |
三个细节决定了后面所有的实现取舍:
- 错误码是系统的,不是库的。
publish被拒时返回的 401 带着系统原文(第 5.3 节的两个 401 全部来自这条透传链),库的职责是包成PushError后一字不改地交给业务层——业务侧拿err.message就能直接对照官方错误码表排障。 - 点击的载体是 wantAgent,时序却是"发布时"。
publish()的那一刻就要把pushId和业务参数封进 wantAgent,等用户点击时系统拉起 UIAbility 并把这些参数塞进want.parameters——中间可能隔着几秒到几天,参数必须是自包含的。 - 事件有三类、三个来源。 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>,避免帧内嵌套对象在严格模式下的类型推断问题。
两个容易被忽略的窗口期:
- 懒连接的首调竞态。 Node 侧的桥是懒连接:第一次
call时才开始探测端口。如果 ArkTS 侧的 server 还没 listen,四个端口全部探测失败会抛push bridge not reachable——所以宿主侧把PushBridgeServer.start()放在页面aboutToAppear,比 Electron 主进程加载 app 更早;Node 侧探测每口 600ms 超时,四次失败后 800ms 退避重连,宁可让调用方多等一秒,不在启动时序上赌运气。 - 断线不能悬挂 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 权限受限等一系列典型坑点。
更多推荐



所有评论(0)