最近在给一个 Flutter 项目做鸿蒙化改造需求说大不大但战线真的长。页面迁移还好说最折磨人的是一堆第三方库在鸿蒙端没有现成的原生实现。这次要搞的是 pusher_channels一个在 Android/iOS 上很成熟的 Pusher 实时通讯客户端。它依赖的原生 SDK 在鸿蒙这边根本不认账想直接在 HarmonyOS NEXT 上跑起来唯一的出路就是自己动手做鸿蒙化适配——用 ArkTS 重写原生侧然后通过 Flutter 的 EventChannel 和 MethodChannel 把 Dart 层和鸿蒙 WebSocket 能力打通。这篇文章不打算空谈概念重点是把我在鸿蒙端把 pusher_channels 跑通的全过程写清楚包括整体方案怎么拆、Dart 层怎么改、ArkTS 侧怎么实现 Pusher 的 WebSocket 握手协议和心跳机制、以及实际踩过的权限、数据序列化、订阅时序这些坑。如果你正在集成本文要讲的实时通讯能力或者正准备把其他 Flutter 三方插件迁移到鸿蒙这篇应该能帮你省不少事。1. 先拆清楚这个适配任务到底难在哪很多同学觉得适配一个 Flutter 插件就是把源码拷过来改改就行这是最大的误解。你要先搞清楚 pusher_channels 原本是怎么工作的才知道鸿蒙化到底要动哪一层。1.1 pusher_channels 的“原生依赖”问题pusher_channels 本质上是 Flutter 对 Pusher 官方客户端能力的一层封装。Dart 层暴露给业务方的是一套看起来人畜无害的 API比如连接、订阅频道、监听事件等。但背后的真实情况是在 Android 端它拉起的是 Pusher 的 Java/Android 客户端在 iOS 端它内部依赖的是 Pusher 的 Swift 客户端。所以你对上层暴露的 Dart 接口本质上全部是由原生能力在支撑。这就带出一个很直接的问题——鸿蒙没有这些原生 SDK就算你把 pusher_channels 的 Dart 源码拖进来编译到鸿蒙包时原生侧直接缺胳膊少腿根本跑不起来。所以适配的本质不是“修改源码”而是“复刻原生行为”。你要在鸿蒙的 ArkTS 环境里把 Pusher 协议栈重新实现一遍包括建立 WebSocket 连接、完成 Pusher 握手、发送频道订阅命令、接收服务端推送事件、处理 ping/pong 心跳等。同时你还要在鸿蒙 Flutter 插件框架里把原本 Android/iOS 的通道逻辑替换成鸿蒙的实现。1.2 鸿蒙 Flutter 插件机制就是把钥匙鸿蒙端跑 Flutter用的通信机制和 Android 系出同门核心就是 MethodChannel 和 EventChannel。这两个词在热词里经常被问到其实就是 Flutter 和原生之间的两条桥。MethodChannel 是“一问一答”的控制通道适合 connect、disconnect、subscribe 这种需要返回结果的命令。EventChannel 是“持续流水”的数据通道适合把 WebSocket 推过来的事件、状态变化源源不断吐给 Dart 层。适配 pusher_channels 的机会就在这原生侧你完全可以用鸿蒙自己的 WebSocket 模块写一套业务逻辑然后按照 Dart 层原本需要的接口语义通过这两种通道重新建立连接。Dart 业务代码不需要大改我们只需要在底层替换了一块“零件”。这其实是 Flutter 组件通信的本质——不同平台的差异被抽象成统一的通道契约适配者只需要保证契约两边都能理解对方。1.3 同类案例okta 鸿蒙适配给的经验在 Flutter 生态里okta 的鸿蒙适配流程和 pusher_channels 非常像。两者都是依赖海外官方 SDK、不提供鸿蒙版本的三方插件。社区里比较靠谱的做法是第一步锁定 Dart 层公开 API把它们当作接口契约第二步用鸿蒙的系统能力实现同等行为第三步通过 EventChannel/MethodChannel 把原生行为桥接回去。okta 适配时开发者把认证操作全部改成了鸿蒙的鉴权服务接口上层 Flutter 代码几乎没动。这套流程完全可以套用到 pusher_channels 的适配中。我建议你先把“契约”想清楚不要一头扎进 ArkTS 代码里。契约稳了后面的事都是体力活。2. 方案设计控制面和数据面分开想在写代码之前我把 pusher_channels 的鸿蒙化方案拆成了两条线控制面和数据面。控制面管的是连接生命周期和订阅动作数据面管的是事件流。两条线分开设计逻辑会清爽很多后面排查问题也方便。2.1 Dart 层如何“动手术”最直接的做法是直接改 pub 包源码但我不推荐。更好的方式是做一个本地包把 pusher_channels 的源码拷到工程里通过 dependency_overrides 指向本地路径然后基于原 API 做兼容扩展。这样不会污染线上依赖改起来也敢大胆。改造后的 Dart 层应该尽量保持原来的调用方式。设计一个抽象接口 PusherClientInterface原 Android/iOS 走原有实现鸿蒙走新的 OHOS 实现。底层用条件导入根据 Platform.isOhOS或者编译宏选择不同的客户端实现。业务侧的 create、subscribe、onEvent 等调用方式保持不变。这种做法的好处很直接如果以后官方支持了鸿蒙你只需要把本地包换回官方依赖业务代码零改动。2.2 控制面MethodChannel设计控制面我统一定义了一组方法名字尽量贴近原插件的能力方便对齐connect传入 appKey、cluster、authEndpoint 等参数disconnect断开连接并清理资源subscribe订阅频道unsubscribe取消订阅trigger向频道触发事件比如客户端事件这里的参数统一用 Map 传入原生侧解析后再决定怎么组装 WebSocket 消息。MethodChannel 的方法名建议带上插件标识避免和别的插件冲突。比如我用的是 pusher_channels_ohos/methods。频道名保持小写和 Pusher 的语义一致。为什么 MethodChannel 适合做这些事因为它的调用是 Future 返回的connect 是否成功、subscribe 是否已响应都能清晰地同步到 Dart 层。反过来事件和状态变化不能用它广播因为那是一次性的响应所以必须走 EventChannel。2.3 数据面EventChannel设计数据面我用 EventChannel 传输四类信息连接状态变化、订阅成功事件、业务事件消息、错误信息。EventChannel 的名字定为 pusher_channels_ohos/events。这里有个非常关键的经验原生侧往 Dart 层传数据尽量传 JSON 字符串不要直接传 Map。很多人觉得 EventChannel 能传 Map 很方便但 Map 经过平台通道序列化以后在某些鸿蒙版本上会出现类型错乱尤其是嵌套 Map 和数组混用的时候。你也不想半夜被线上「收到个类型错误」的日志叫醒吧所以我的做法是所有事件统一在原生侧组装成 JSON 字符串Dart 层再自己解。格式统一排查也容易。我在 Dart 层做了这么几个事件回调onConnectionStateChange、onEvent、onError、onSubscriptionSucceeded。其中 onEvent 接收的是带 channel 和 data 的完整模型里面的事件名、频道名、负载靠解析 JSON 字符串获得。3. 实操实录ArkTS 侧把 Pusher 协议跑起来方案定了后面的活就聚焦在鸿蒙原生侧了。下面这段是我的实际操作过程代码是基于当前版本的 ArkTS 写的如果你用的 SDK 版本不同接口签名可能会有一点偏差但整体思路是通用的。3.1 工程准备与权限配置首先在鸿蒙 Flutter 工程的 ohos 目录里创建一个 Flutter 插件模块或者直接手工注册插件取决于你工程的脚手架。无论哪种方式最后都要保证 Flutter 引擎能加载到这个原生插件。然后是最容易漏的一步——网络权限。如果 module.json5 里不显式声明 ohos.permission.INTERNETWebSocket 会直接连不上而且错误日志不直观就像“超时”。我一开始就是在这里卡了半小时后来在module.json5的 requestPermissions 里加了权限声明{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ] } }提一句在鸿蒙开发中网络权限属于敏感权限应用市场审核时也会看。适配第三方插件不要省这一步。3.2 在 ArkTS 里创建 WebSocket 连接鸿蒙提供的 WebSocket 模块API 12 之后的推荐写法是通过 kit.NetworkKit 引入。部分旧版本 SDK 还支持import webSocket from ohos.net.webSocket我用新写法同时保留了兼容性判断的注释方便团队在不同机型上验证。import { webSocket } from kit.NetworkKit; import { BusinessError } from kit.BasicServicesKit; export class PusherWebSocket { private ws: webSocket.WebSocket | undefined; private socketId: string ; connect(appKey: string, cluster: string): Promisevoid { const url wss://ws-${cluster}.pusher.com/app/${appKey}?protocol7clientohos-flutterversion1.0.0; this.ws webSocket.createWebSocket(); return new Promisevoid((resolve, reject) { this.ws!.on(open, (err: BusinessError | undefined) { if (err) { reject(err); return; } // 连接已打开等待 connection_established 事件 }); this.ws!.on(message, (err: BusinessError | undefined, value: string) { if (err) { this.handleError(err); return; } this.handleServerMessage(value); }); this.ws!.connect(url, (err: BusinessError | undefined) { if (err) { reject(err); return; } resolve(); }); }); } }这段代码的要点是连接地址由 appKey 和 cluster 确定这是 Pusher 的固定 WebSocket 地址规则。protocol7是经典的 Pusher 协议版本号大部分客户端都用这个。不要小看这个参数之前有人用错协议号服务和客户端反复握手失败浪费一个下午。3.3 完成 Pusher 握手和订阅流程WebSocket 连接建立后Pusher 不会马上让你收业务消息。服务端会先下发一条connection_established事件里面携带了一个socket_id这个东西非常重要。你要先把它存下来后续订阅私有频道或进行鉴权时都要用到。我在 handleServerMessage 里做了这样的分发判断。先把收到的字符串解析成对象再根据 event 字段决定走哪个分支private handleServerMessage(raw: string) { const msg JSON.parse(raw); switch (msg.event) { case pusher:connection_established: this.socketId msg.data.socket_id; this.onConnectionStateChange(connected, this.socketId); // 此时再执行积压的 subscribe 请求 this.flushSubscribeQueue(); break; case pusher:subscribe_succeeded: this.onSubscriptionSucceeded(msg.channel); break; case pusher:pong: // 心跳回复不需要额外处理 break; default: // 普通业务事件透传给 Flutter this.onEvtReceived(msg.channel, msg.event, msg.data); } }发送订阅请求时要遵循 Pusher 的消息格式。第一次写很容易把 subscribe 包装成乱七八糟的结构Pusher 会直接无视你。正确的格式是{ event: pusher:subscribe, data: { channel: my-channel } }对应 ArkTS 里直接构造字符串发送public subscribe(channel: string) { if (!this.socketId) { // 握手还没完成先放到队列里等 connection_established 再发 this.subscribeQueue.push(channel); return; } this.sendMessage(JSON.stringify({ event: pusher:subscribe, data: { channel } })); }这里有一个非常容易踩的坑如果在 connection_established 之前就调用 subscribe服务端会直接把这条消息丢弃而且不会报错。所以我们做了一个 pending 队列等 socket_id 拿到之后再统一 flush。这个设计救了很多次场。3.4 心跳机制的具体实现WebSocket 本身也有 TCP 层的心跳但在移动端尤其是鸿蒙这种系统网络切换、后台休眠非常频繁光靠 TCP 心跳远远不够。Pusher 服务端会定期发送pusher:ping客户端需要响应对应的pusher:pong否则服务端会认为连接死了关闭连接。在 handleServerMessage 里要处理这个 ping 事件case pusher:ping: this.sendMessage(JSON.stringify({ event: pusher:pong })); break;不过我的实测经验是应用长时间退到后台后部分网络环境会把这条连接静默杀掉也就是 TCP 还挂着但数据已经不通了。这时候客户端要自救在 Dart 层或原生层加一个应用级心跳每 15 到 20 秒主动发送一次 ping并监听回调来判断连接是否存活。如果连续两次没有收到任何响应就主动 close 后重连。这个策略能显著提升推送到达率尤其是弱网场景下。Dart 侧可以起一个 Timer调用原生侧发送 pingTimer.periodic(Duration(seconds: 15), (timer) { _channel.invokeMethod(ping); });原生侧收到 ping 动作时如果真的还连着就直接发一个pusher:ping字符串。同时维护一个 lastReceived 时间戳用于判断超时。4. 实战中的常见问题与排障笔记整个适配过程中踩的坑不少有些是鸿蒙特性造成的有些是 Pusher 协议本身的细节。我整理成一份速查表希望你能绕过去。4.1 权限缺失设备上一直超时排查思路先确认 WebSocket 地址能不能用浏览器连上排除服务端问题。接着看鸿蒙端日志里有没有 Permission denied 相关报错。如果有基本是 module.json5 缺了 INTERNET 权限。这个问题的坑在于有些设备上错误日志不明显表现为连接超时很容易误判成网络问题。4.2 消息全乱EventChannel 序列化问题如果用 MethodChannel 或 EventChannel 直接传 Map一旦数据里有嵌套 Map 或者包含大量 JSON 数据鸿蒙端在序列化时偶尔会发生字段丢失。最稳的方案是原生侧直接传 JSON 字符串Dart 层用 jsonDecode 自己解。我最后把所有事件统一改成 String 传输数据格式问题再没出现过。4.3 后台切回后收不到消息看到热词里有人在问 flutter navigator 切换页面后状态会不会丢这里要分清楚路由切换不会丢连接但如果鸿蒙的 Ability 被系统回收了Flutter 引擎和原生插件都要重建WebSocket 连接自然就没了。这时候不能只在原生层被动等断线回调建议在 Dart 层的生命周期里监听应用从后台恢复的事件主动检查连接状态断了就重连。4.4 订阅时序connection_established 还没到这个前面已经提过属于必须处理的经典场景。我再强调一下不要在连接打开那一刻就发 subscribe。Pusher 要求先收到 connection_established 事件、拿到 socket_id 之后才能订阅频道。准备一个订阅队列等握手完成再批量下发是最简单的解决方式。4.5 类型错误集中在私有频道鉴权如果业务用了私有频道订阅前要走 authEndpoint 进行鉴权需要在 subscribe 时把 socket_id 带上。这个时机也很讲究。不能太早socket_id 还没生成也不能太晚服务端会拒绝。建议把私有频道的 presence 和 private 前缀单独做个判断在鉴权成功后再触发原先的 subscribe 逻辑。我把排障经验整理成了表方便你对照现象可能原因解决方案连接一直超时缺少 INTERNET 权限module.json5 增加权限声明握手能完成但订阅不成功没有等 connection_established维护订阅队列拿到 socket_id 再发收到事件但不是 JSON 对象EventChannel 传 Map 被序列化破坏统一通过字符串传输 JSON退后台一段时间后收不到推送底层连接被静默断开应用级 ping 心跳 超时重连私有频道订阅失败socket_id 未正确参与鉴权在鉴权载荷里带上 socket_id还有一点需要单独提醒如果你同时在做 Flutter 原生视图相关的适配比如 PlatformView一定不要把它和插件通道混在一个模块里。PlatformView 是另一套渲染桥接逻辑把两者混着排查会把问题搞得很乱。我一开始就是因为把 EventChannel 和原生视图的代码放在了一起导致事件回调迟迟不触发排查时走了很多弯路。最后再分享一个小技巧鸿蒙适配过程中日志是最重要的朋友。WebSocket 的 on(message) 回调里尽量把原始字符串打出来尤其是握手阶段。不要只打“收到消息”这种没营养的日志把 event 类型和 socket_id 完整打印出来只要看到 connection_established 后面的 socket_id 和业务请求里的 socket_id 对不上你就能立刻定位到是握手解析问题而不是网络问题。这套调试习惯救了我很多次希望你用的时候也能少走弯路。
