Flutter 鸿蒙插件适配实战：用 connectivity_state_plus 0.1.10 判断网络与 TCP 可达性

●VON

4人浏览 · 2026-09-14 10:52:41

●VON · 2026-09-14 10:52:41 发布

适配仓库： https://atomgit.com/oh-flutter/connectivity_state_plus

适配分支： feat/ohos_connectivity_state_plus_0.1.10

受测提交： 2fb00966f0c077d5419b02e3339bd185503f7acf

一、最终效果与适配目标

业务里“连着 Wi-Fi”和“目标服务能连通”不是一回事。connectivity_state_plus 同时提供系统网络接口状态和 Dart TCP 探测，本次 OHOS 适配只补平台网络查询与事件，让原有 Dart 层继续负责地址解析、Socket 超时、缓存和 restricted 状态。

在这里插入图片描述

图 1：真机当前默认网络为 Wi-Fi；环回开放端口连接成功，服务器关闭后连接失败，两个方向均符合预期。

在这里插入图片描述

图 2：取消网络订阅后，页面保留已有结果并显示监听暂停。

在这里插入图片描述

图 3：重新订阅后获得新的 Wi-Fi 首值，证明订阅生命周期可以重新建立。

验证点	实测结果	证据
系统网络查询	`checkNetworkConnectivity()` 返回 `wifi`	图 1、图 8
网络事件	首值、取消和重订阅通过	图 2、图 3
一次性 TCP 探测	开放环回端口 true，关闭后 false	图 1、图 8
自动化与构建	21 Dart + 3 Widget + 11 ArkTS，共 35 项及 HAP 通过	图 6、图 7
静态检查边界	根工程保留 1 条上游 Web `dart:html` 弃用 info，示例无问题	图 6

二、成果速览

项目	内容
上游基线	0.1.10，提交 `39395bc6e22a63883a0df0003e43a508d6567b88`，MIT
适配分支	`feat/ohos_connectivity_state_plus_0.1.10`
适配提交	`2fb00966f0c077d5419b02e3339bd185503f7acf`
新增 OHOS 能力	多承载类型查询、默认网络事件、首值、去重、取消与重绑
保持不变的接口	`Connectivity`、`ConnectivityState` 及上游 connectivity 通道
权限	`GET_NETWORK_INFO`、`INTERNET`
真机结论	Wi-Fi 与环回 TCP 双向结果通过；外网、VPN、真实网络切换未验

2026 年 9 月 11 日核对时，0.1.10 是最新发布代码，适配组织与清单中没有同包名 OHOS 实现。这个版本刚加入 onNetworkConnectivityChanged，因此直接以最新接口契约适配，避免先适配旧版再重复迁移。

三、实测环境

组件	实测版本
Flutter OH	`3.41.10-ohos-1.0.1`
Dart	`3.11.5`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26；示例兼容 API 18
真机	CHZ-AL00，HarmonyOS `7.0.0.105`
插件	`connectivity_state_plus 0.1.10`

环境搭建参考 Flutter OH 环境搭建指南。本文实测稳定版 3.41.10-ohos-1.0.1；3.44.9+ohos-0.0.1-canary1 是预览版。

四、同步代码与补全平台壳

git clone https://atomgit.com/oh-flutter/connectivity_state_plus.git
cd connectivity_state_plus
git switch -c feat/ohos_connectivity_state_plus_0.1.10 39395bc6e22a63883a0df0003e43a508d6567b88
flutter create --template=plugin --platforms=ohos --no-pub .

我保留原 Dart TCP 逻辑与其他平台代码，新增 ConnectivityStatePlusPlugin、OHOS 示例、双语文档和三层测试。通道继续使用上游平台接口约定的 dev.fluttercommunity.plus/connectivity 与 dev.fluttercommunity.plus/connectivity_status。

在这里插入图片描述

图 4：AtomGit origin、适配分支、完整 HEAD 和工作区状态。

五、先区分三个公开查询

final Connectivity connectivity = Connectivity();

final ConnectivityState network =
    await connectivity.checkNetworkConnectivity();
final bool reachable = await connectivity.checkAddressConnectivity(
  'https://example.com:443',
);

connectivity.setAddressCheckOption('https://example.com:443');
final ConnectivityState combined = await connectivity.checkConnectivity();

checkNetworkConnectivity() 只看系统接口，不返回 restricted。checkAddressConnectivity() 是一次性 Dart TCP 连接，不改变全局探测地址，也不走 5 秒缓存。setAddressCheckOption() 配置地址后，checkConnectivity() 才会把 Wi-Fi/蜂窝与 TCP 结果组合，探测失败返回 restricted。

事件也分两层：onNetworkConnectivityChanged 只报告系统接口；onConnectivityChanged 会在已配置地址时执行 TCP 探测。应用不能把 restricted 当成整个互联网断开，它只说明本次目标地址探测失败。

六、OHOS 多承载类型与事件生命周期

OHOS 插件查询默认网络 capabilities，要求存在 NET_CAPABILITY_INTERNET，再按固定顺序输出 wifi、ethernet、vpn、mobile、bluetooth。没有默认网络、无效句柄或缺少 Internet capability 返回 ['none']，未知承载返回 ['other']。系统调用抛错则上抛 network_query_failed，不能伪装成离线。

if (!connection.hasDefaultNetSync()) return ['none'];
const handle = connection.getDefaultNetSync();
const capabilities = connection.getNetCapabilitiesSync(handle);
if (!capabilities.networkCap?.includes(connection.NetCap.NET_CAPABILITY_INTERNET)) {
  return ['none'];
}

事件监听使用默认 NetConnection，注册成功后发送首值；四类变化回调都重新查询。相同列表用规范顺序拼接后去重。取消早于注册、旧订阅回调、注册失败、注销失败和 Engine 重绑都有显式清理逻辑。

在这里插入图片描述

图 5：默认网络 capabilities 映射、错误传播和事件订阅实现。

插件 HAR 声明 ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET。前者用于系统网络信息，后者用于业务侧 Socket 探测；均为系统授权权限，不需要用户弹窗。

七、自动化、构建与遗留 info

flutter pub get
flutter analyze --no-fatal-infos
flutter test
node --test ohos/test/connectivity.test.cjs
cd example
flutter analyze
flutter test
flutter build hap --debug --no-codesign

21 项 Dart、3 项 Widget、11 项 ArkTS，共 35 项通过。Dart 用例覆盖 TCP 成功/失败、默认端口、超时、并发共享、5 秒缓存失效和一次性探测；原生用例覆盖多承载排序、none/other、查询错误、首值、去重和生命周期。

根目录 analyze 仍有 1 条来自上游 Web 实现的 dart:html 弃用 info，所以用 --no-fatal-infos 返回 0 并保留记录；OHOS example 静态分析无问题。这条 info 不是 OHOS 构建失败，也没有被文章隐去。

在这里插入图片描述

图 6：35 项测试、示例分析和上游 Web 弃用 info 的真实口径。

在这里插入图片描述

图 7：无签名 HAP 元数据及固定受测提交。

八、固定提交与真机验证

dependencies:
  connectivity_state_plus:
    git:
      url: https://atomgit.com/oh-flutter/connectivity_state_plus.git
      ref: 2fb00966f0c077d5419b02e3339bd185503f7acf

远程 Git 依赖在隔离宿主中解析到同一 SHA，签名构建和安装通过。真机基础探测得到 Wi-Fi，并完成订阅首值、取消、重订阅。为避免把公网波动写成库失败，我在设备本机启动临时环回 ServerSocket：端口开放时 TCP 为 true，关闭服务器后同地址为 false，验证一次性探测的成功和失败两条路径。

在这里插入图片描述

图 8：Wi-Fi、环回 TCP 和订阅结果，以及未覆盖的外部网络边界。

默认网络 API 对 VPN 的可见性受系统路由策略限制，本文没有把 checkVPNConnectivity() 写成 OHOS 已验收能力；外网 DNS、目标服务、Wi-Fi/蜂窝真实切换也未验证。

应用内详情：重新执行环回 TCP

在这里插入图片描述

图 9：再次执行真实环回测试，开放端口连接成功，关闭端口后连接失败（预期），事件记录保留本次通过结果。

九、FAQ

Q1：为什么 Wi-Fi 正常却返回 restricted

现象： 系统接口是 Wi-Fi，checkConnectivity() 返回 restricted。
原因： 业务配置了探测地址，而该 TCP 连接在本次或缓存周期内失败。
解决方法： 先用 checkNetworkConnectivity() 判断接口，再把探测结果作为目标服务信号；不要替代真实 HTTP 错误。
验证结果： 真机开放/关闭同一环回端口分别得到 true/false。

Q2：为什么地址修改后不能沿用旧缓存

现象： 更换目标服务后仍短暂看到旧可达结果会造成误判。
原因： 5 秒缓存只对同一个配置地址有效。
解决方法： setAddressCheckOption() 变更地址时递增 generation，并清空缓存和进行中引用。
验证结果： Dart 测试覆盖地址切换期间旧异步结果不能污染新配置。

Q3：为什么根 analyze 不是零输出

现象： 检查报告保留一条 dart:html 弃用 info。
原因： 它来自上游 Web 兼容文件，与新增 OHOS 实现无关。
解决方法： 当前用 --no-fatal-infos 记录并继续 OHOS 验证，后续单独迁移 Web API。
验证结果： example analyze、35 项测试和 HAP 均通过，遗留 info 未被误写成 warning 清零。

十、总结

本次适配让 connectivity_state_plus 0.1.10 在 OHOS 上获得真实默认网络查询与事件，原 Dart TCP 探测、缓存和 restricted 语义保持不变。35 项自动化、HAP 构建、Wi-Fi 查询、订阅重建及环回 TCP 成败路径均已验证。

当前仍需补外网可达、VPN、真实 Wi-Fi/蜂窝/离线切换和更多设备。使用方应锁定完整 SHA，并把接口状态、TCP 探测和真实业务请求分层处理。

十一、参考链接

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

中华正歌（原创诗）

人工智能6S服务平台

Flutter 鸿蒙插件适配实战：用 power_saver_plugin 0.0.1 读取电量并监听省电模式

人工智能6S服务平台

让昇腾更好用：从开发旅程出发，把易用性落到实处

MindStudio InSight 2.0发布，业界首次实现Agent与可视化交互性能分析，内置调优MCP与Skill，让开发者既能看见数据，又能获得可落地的优化建议，性能调优不再“凭感觉”。当前，昇腾已启动28个领域加速库，覆盖9个AI领域，其中17个协同高校生态共建，覆盖深度学习、多模态、数学库、推荐、智驾、AI4SCIENCE等领域。开发者期望的AI开发体验，始于流畅的“开箱即用” ——无