前阵子接手一个“大屏盒子类”项目的网络稳定性改造现象很典型用户隔三差五反馈“开机后应用一直转圈”“有线网络明明插着却提示无网络”“电视上Wi-Fi图标显示已连接但视频就是拉不动”。排查到最后问题基本都落在同一个点上——应用层只看到了系统给的“网卡连接状态”却不知道这条链路是不是真的能通到外网。Flutter 生态里有现成的 data_connection_checker 这类库做“真连接检测”而我们手里的目标平台又要以鸿蒙系统为主于是就有了这次的 data_connection_checker_tv 鸿蒙化适配也算是一套面向大屏连接资产与可用性治理的落地实践。这篇内容主要给三类人看一是 Flutter 应用要往鸿蒙迁移、正好遇到网络检测类三方库需要适配的开发者二是做智慧屏、机顶盒、投影仪这类大屏设备应用、被“伪网络连接”反复坑过的同学三是对“如何把设备连接状态真正变成可观测、可治理的业务资产”感兴趣的人。下面把我从方案选型到代码落地的全过程以及踩过的几个比较隐蔽的坑一次性讲清楚。1. 从 data_connection_checker 到 _tv大屏设备为什么需要另一套网络检测1.1 只靠网卡状态判断“有没有网”本质上是看门狗没带眼睛传统做法里很多 Flutter 应用判断网络只依赖 connectivity_plus 这类包返回的 ConnectivityResult。它能告诉你当前是 Wi-Fi、蜂窝还是以太网但注意这个结果只是“有没有网络接口、拿到没拿到 IP 地址”它完全不关心你连的这个网络是不是真的能访问互联网。想象一个场景路由器拨号失败但局域网还是通的电视通过 DHCP 拿到了 192.168.x.x 的地址系统层面当然认为“WLAN 已连接”你的应用也收到了 connectivity 的回调然后开始拉数据——结果所有请求全部超时。这就是典型的“伪网络连接”。data_connection_checker 这个库的思路其实很实在先把系统连接类型拿一遍如果是 none 直接判 false接着做一个 DNS 解析看能不能把域名解析成 IP最后再对一组已知的可达服务器做 TCP 连接探测只要有一个成功就算“网络可用”。这一套下来判断的就不仅仅是“有没有网卡”而是“这条链路能不能承载业务”这也是标题里说的“精密”二字的本质。1.2 TV 变体与普通版本的核心差异连续性检测与混合链路那 _tv 变体改了什么从我实际使用的感受来看它把原来“一次性的检查”扩展成了“持续的连接状态观察”默认不再由调用方反复手动 check而是内部维护一个连接状态流按固定周期执行检测状态变化时主动推送对以太网和 Wi-Fi 混合场景更友好因为大屏设备经常是“有线为主、无线备用”链路切换时普通版本很容易出现一次检测失败就直接判定不可用缺少重试和安抚逻辑检测结果的粒度也更贴近 UI 展示需求最少要能区分“完全离线”“链路有地址但外网不通”“一切正常”这三档而不是笼统的 true/false。所以在做鸿蒙适配之前我先把它的功能拆成了两层一层是利用系统网络能力获取“网络类型、网络是否可用、能力集”的底座层原先依赖 connectivity_plus另一层是真正对外提供连续状态流的 Dart 业务层。这样一拆鸿蒙化的工作面就很清晰了——我只需要把底座层的原生能力换成鸿蒙系统的 NetworkKitDart 层保持原有调用语义上层业务就完全不用动。2. 鸿蒙化适配的技术路线不改 Dart 业务的前提下替换底层两个能力2.1 先盘点依赖这个包不是纯 Dart卡点在原生通道很多人在做鸿蒙化的时候上来就翻源码其实第一步应该是看 pubspec.yaml。data_connection_checker_tv 本身的核心逻辑确实在 Dart 侧但它的网络类型获取依赖 connectivity_plus而 connectivity_plus 是个标准联邦插件Android 侧走 ConnectivityManageriOS 侧走 NWPathMonitor。如果 connectivity_plus 生态已经有鸿蒙适配版本那事情简单很多但现实是鸿蒙社区版的 connectivity 类插件往往要自己维护或者公司内部有统一封装。我当时盘完依赖后的结论是与其去 patch 一个第三方 connectivity 插件不如在鸿蒙侧自己做一个轻量的“网络能力提供者”把系统网络事件通过平台通道灌给 Dart。这样适配点集中在我们自己手里后续鸿蒙系统 API 升级、权限变更都好控制。2.2 能力映射Android 网络 API 与鸿蒙 NetworkKit 的对应关系适配的本质就是把 Android 上的能力在鸿蒙里重新实现一遍。我用一个表把两边 API 做了映射这也是评审方案时最重要的一个文档能力点AndroidOpenHarmony / HarmonyOS获取默认网络ConnectivityManager.getActiveNetworkconnection.getDefaultNet获取网络能力是否有 InternetNetworkCapabilities.NET_CAPABILITY_INTERNETconnection.getNetCapabilities(netHandle)获取链路信息LinkProperties / DnsServers / LinkAddressesconnection.getConnectionProperties(netHandle)监听网络可用事件ConnectivityManager.NetworkCallback.onAvailableconnection.on(netAvailable)监听网络丢失事件NetworkCallback.onLostconnection.on(netLost)监听能力变化NetworkCallback.onCapabilitiesChangedconnection.on(netCapabilitiesChange)获取全部网络ConnectivityManager.getAllNetworksconnection.getAllNets注意一个细节鸿蒙的 getDefaultNet 返回的是 NetHandle它是一个自增句柄不是 Android 那种 Network 对象。你在判断“当前网络是不是有线”的时候不能直接拿句柄和网络类型比对而是要用 handle 再调 getConnectionProperties看里面有没有包含对应网卡信息。这个间接层很容易被忽略。2.3 两种实现路径纯 Dart 重写探测 vs 平台通道桥接到底要不要走平台通道我对比过两种方案方案 A把 DNS 解析和 TCP 探测都用 Dart 的 dart:io 来写鸿蒙侧只负责把“当前网络类型和是否处于在线状态”传给 Dart。优点是改动小、可复用原库逻辑缺点是 dart:io 里的 Socket 行为在鸿蒙 Flutter 引擎上虽然基本可用但一旦涉及网卡切换、系统网络栈还没有完全就绪Dart 层拿到的时机不如原生层准确。方案 BDart 层只做状态编排和对外接口鸿蒙侧通过 ArkTS 直接使用 NetworkKit 和 SocketKit 完成连接探测。优点是更贴近系统能力能拿到更精确的事件回调也能顺带补齐信号级、链路级的“精密”信息缺点是多了一层编解码工作量翻倍。最终我选的方案 B而且我建议后续做鸿蒙化网络类插件的人都优先考虑这条路。原因很实际鸿蒙系统的网络事件回调时机和 Android 不一样比如系统广播“网络丢失”的触发点更滞后如果你把这些逻辑全压在 Dart 层很难稳定复现和调试把关键检测下沉到 ArkTS至少每次出问题你可以用系统日志快速定位是系统没给事件还是自己的探测逻辑出了问题。3. 核心探测逻辑落地ArkTS 侧实现“真连接检测”3.1 监听系统事件netAvailable / netLost / netCapabilitiesChange 的正确用法ArkTS 侧监听网络状态核心就是 NetworkKit 的 connection 模块。我在工程里新建了一个网络能力类负责三件事获取默认网络、监听系统事件、执行可用性探测。先看系统事件监听的写法对应 ArkTS / Stage 模型import { connection } from kit.NetworkKit; export class NetworkMonitor { private netHandle: connection.NetHandle | null null; startMonitor() { // 先拿当前默认网络 connection.getDefaultNet().then((handle) { this.netHandle handle; this.checkCapabilities(handle); }); // 网络可用 connection.on(netAvailable, (handle) { this.netHandle handle; this.checkCapabilities(handle); this.notifyDart(available, handle); }); // 网络丢失 connection.on(netLost, (handle) { if (this.netHandle handle.netId this.netHandle.netId) { this.notifyDart(lost, null); } }); // 能力变化比如从蜂窝切到 Wi-Fi或者网络从可用变不可用 connection.on(netCapabilitiesChange, (_handle, netCap) { const hasInternet netCap.bearerTypes.length 0; this.notifyDart(capabilitiesChanged, hasInternet); }); } }这里面最容易翻车的点是 netLost 的回调时机。实测在部分鸿蒙版本上路由器断电后 netLost 要过好几秒才回调而 netCapabilitiesChange 反而先触发且此时网络其实已经废了。如果业务层只监听 netLost就会有一段时间的“状态真空期”。我的做法是把“系统事件 主动探测”结合收到任何事件都触发一次主动探测用探测结果覆盖系统事件的判断而不是直接拿系统事件当最终状态。3.2 主动探测TCP 连接 DNS 解析的双重校验data_connection_checker 的原始思路是 DNS 解析加 TCP 连接。鸿蒙 ArkTS 里做 TCP 连接可以用 kit.NetworkKit 的 socket 模块也可以退而求其次直接在 Dart 侧用 dart:io。方案 B 决定下沉到原生我写了一个探测函数import { socket } from kit.NetworkKit; function probeNetwork(): Promiseboolean { return new Promise((resolve) { const tcp: socket.TCPSocket socket.constructTCPSocketInstance(); const address: socket.NetAddress { address: 223.5.5.5, // 探测目标可配置 port: 53, }; tcp.connect(address).then(() { tcp.close(); resolve(true); }).catch(() { tcp.close(); resolve(false); }); // 超时控制 setTimeout(() { tcp.close(); resolve(false); }, 3000); }); }目标服务器的选择有讲究。原库默认的探测目标是谷歌的公共 DNS但这个在国内的连通性不稳定适配到我这边项目上肯定要换。我最终的探测策略是第一优先目标是内网网关地址加常见端口比如网关 IP 的 53 端口用来验证“局域网链路通不通”第二优先是公网 DNS 服务比如 223.5.5.5:53用来验证“外网可达性”第三优先是业务自己的后端域名比如 api 域名加 443 端口用来验证“业务链路通不通”。这三个目标的意义完全不同分别对应“链路层”“出口层”“服务层”。做可用性治理的时候三个层级的探测结果都要保留而不是压成一个 boolean 丢给上层。3.3 把结果回传 DartEventChannel 的设计与状态一致性探测结果要回传给 Flutter 侧我用的 EventChannel通道名定义成data_connection_checker_tv/network_status。这里有几个经验不要在每次探测后都往 Dart 推一次完整结果否则大屏上日志刷得飞快。正确做法是只有在“状态发生变化”时才推送Dart 侧再做一层去重。推送的数据结构要固定成版本化字段方便以后加字段不断兼容。我定义的是{ type: available, timestamp: 1710000000000, networkType: ethernet, networkAvailable: true, internetAccessible: true, probeTargets: [223.5.5.5, api.xxx.com] }Dart 侧接收时用一个 sealed class 来建模不要直接塞 Map否则状态多了代码会很乱。4. 大屏连接资产治理把“是否在线”变成可观测的业务数据4.1 连接资产的建模设备、链路、服务三层“大屏连接资产”这个词一开始听起来很抽象实际落地后其实就是三件事设备信息、链路信息、服务状态。我把它们建模成一个NetworkAsset对象每条记录长这样字段含义典型值deviceId当前设备的唯一标识STB-XXXXlinkType当前链路类型ethernet / wifi / nonelinkAddressIP 地址192.168.1.100gateway网关192.168.1.1dnsListDNS 列表[223.5.5.5, 10.0.0.1]internetState外网可用状态true / falselatencyMs探测 RTT35lastUpdate最近更新时间时间戳这个建模的意义在哪里当用户上报“大屏看不了视频”的时候你不需要再问“你家网络是不是好的”。看这个资产表如果 internetState 为 false就可以直接判断问题出在网络链路如果 true 但视频还是拉不动那问题就转向了业务服务端。这就是“连接资产治理”的降噪能力。我还做了一条“资产流水线”每次网络状态变化都追加一条记录到本地数据库并在一定条件下上报。这样后期审计“这个设备今天是不是反复断网”时有据可查而不是靠用户手抄。4.2 可用性治理实战断线重连、切换重试与无感恢复治理动作可以分成三层。第一层是“开机阶段”的特殊处理。大屏/机顶盒开机时有线网口可能还没有完成协商DHCP 还没拿到 IP这时候如果应用立刻去拉数据必然失败。我之前在 Android 上容易踩鸿蒙上同样存在。解决办法是应用启动后不要立刻开始网络探测给系统两三秒settle时间然后再触发第一次完整探测如果第一次失败用退避策略重复探测间隔按 1s、2s、4s、8s 递增最多重试五次。第二层是“网络切换”的处理。有线网线被拔掉后系统在几秒内可能切到 Wi-Fi这时候不能因为一次探测失败就直接在 UI 上展示“网络不可用”的拦截页。正确做法是切换到新链路后先做一轮快速探测1 秒间隔、连续三次只要有一次成功就认为链路恢复UI 上做“无感恢复”不要闪断。第三层是“主动探活”。如果设备长时间播放视频或者处于待机状态网络可能悄悄断开。我按 30 秒一个周期做轻量探测只连网关 53 端口如果网关通了但外网断了再降级成“仅局域网可用”状态并延迟到网络恢复后自动恢复完整功能。这个 30 秒是经验值太频繁会影响大屏 CPU 和发热太稀疏又无法及时发现问题。4.3 日志与上报现场还原问题的关键信息做可用性治理最怕的是“用户说没网但日志里什么都查不到”。所以我的日志规范是每条网络事件都要带探测链路信息、时间戳、当时的网络类型和探测结果。比如[NET] 2025-06-10 10:00:01.123 | typewifi | internettrue | rtt42ms | probectorrent [NET] 2025-06-10 10:00:31.456 | typewifi | internetfalse | probetimeout(3000ms)日志不能只记“成功/失败”还要记录探测目标、超时时间、当时网络能力集。这样远程排查的时候才可以回答“到底是系统没给网卡还是出口被封还是服务端不可达”这三个层次的问题。5. 适配过程中值得记录的坑5.1 超时时间别拍脑袋3 秒可能真的不够刚开始我把 TCP 探测超时设成 2 秒结果很多弱网环境下出现大面积误判“网络不可用”。后面抓日志才发现链路质量差的时候TCP 握手很容易在 2 秒边缘失败而且重试还会引起雪崩。最终我把超时改成 3 秒并把探测次数从 1 次改成 2 次只有两次都失败才判定不可用。虽然检测延迟增加了一点但对大屏场景来说宁可晚两秒上报不能误杀正常连接。5.2 鸿蒙的 netLost 回调滞后别依赖单一事件前文已经提过这里再强调一下在鸿蒙上当路由器断电或者上游网络断开时系统回调的时序可能和 Android 完全不一样。有可能先收到 netCapabilitiesChange几秒后才收到 netLost甚至有些版本收不到 netLost。我踩了一次线上事故就是完全依赖 netLost 做状态切换结果设备端停留在“已连接”状态长达四分钟。解决办法是打破“等事件”的思维改成“事件触发探测探测结果为准”。所有系统事件只当作探测的启动信号最终状态以探测返回值来驱动这样不管系统回调怎么“迟到”状态机都会收敛到真实情况。5.3 权限申请与实际能力校验GET_NETWORK_INFO 不是可选配置鸿蒙上做网络信息获取需要在 module.json5 里声明权限而且不同 API 版本对权限的要求有差异。我这里遇到的问题是低版本只要求 ohos.permission.GET_NETWORK_INFO高版本又额外要求 INTERNET 权限才能做网络探测。如果权限缺失系统 API 会静默返回空值而不是抛异常。排查这种问题最容易浪费半天时间。建议在适配时写一个权限自查函数在启动时检查这几个权限并用 toast 或者调试页暴露出来而不是等到用户报障才去猜。5.4 Dart 侧 EventChannel 的生命周期管理重启大屏应用后收不到事件这个问题比较隐蔽但很常见。大屏应用从后台被系统回收后Flutter engine 会重建但鸿蒙侧的 NetworkMonitor 如果还留着原来的监听Dart 侧重新注册 EventChannel 时会发现事件推送不到。原因是 EventChannel 的 listener 在 engine 重建后已经失效原生侧还在往旧的 stream 里塞数据。我的处理方案是原生侧监听系统网络状态后不主动往 Dart 推而是每 1 秒发一个“心跳事件”Dart 侧收到心跳后如果发现状态哈希不一致就主动调 MethodChannel 拉一次全量网络状态。这样即使中间事件丢失也能在下一次心跳时恢复同步。心跳本身也非常轻量不会引入明显开销。5.5 大屏设备发热与 CPU 占用高频探测的隐性成本有很长一段时间我的检测逻辑写得比较奔放每 5 秒做一次完整的三层探测结果大屏盒子的 CPU 占用率往上蹿了 20%。大屏虽然插着电看起来不怕耗电但系统会因过热触发降频最直接的表现就是本来流畅的桌面变得卡顿。后来我把探测分级了。平时只做“局域网网关连通性”的轻探测间隔 30 秒只有发现链路异常时才进入密集探测模式间隔 2 秒连续探测 5 次后如果没有恢复再降回轻探测并且记录一次异常事件。这样既保证了异常发现的及时性又不至于让 CPU 一直满负荷喘气。一点实操体会整个适配完成后最深的感受是网络检测类三方库的鸿蒙化难点通常不在“翻译”代码而在“重新理解系统行为”。鸿蒙的网络 API 设计更偏向“能力集”和“可用状态”总体描述和 Android 的 ConnectivityManager 有不少差别而且系统回调的时序有自己的脾气。如果只是机械地把 Android 经验搬过来上线后大概率会在弱网切换、开机初始化这些节点上出问题。如果后面有人要重复做类似的事我的建议是先把原库的功能拆成“系统能力获取”和“业务状态编排”两层原生侧只负责提供准确、带事件通知的系统事实Dart 侧负责把事实翻译成业务可用的连接状态流探测目标和超时参数全部做成可配置的不要硬编码最后无论是开发还是排查问题都要以“事件 探测结果互相印证”的思路来处理而不是盲信任何一个信息来源。做好这几点大屏连接资产这块复杂的网络状态才能真的变成可控、可观测的业务底盘。