更新记录

1.0.0（2026-06-07） 下载此版本

初次提交

平台兼容性

uni-app(5.0)

uni-app x(5.0)

laoqianjunzi-net

laoqianjunzi-net 是一个面向 uni-app / uni-app x 的网络诊断与地址快照插件，聚焦 5 组当前可直接使用的能力：

• 目标连通性探测
• 本机地址读取
• 网卡快照采集
• 局域网 IPv4 网段扫描
• 诊断日志开关

插件设计目标是让页面层直接拿到结构化结果，而不是自行解析各端零散输出。文档内容聚焦当前正式导出的主 API 与实际平台行为。

适用场景

• 登录前网络自检
• 设置页展示当前 IP / 网卡状态
• 局域网设备发现
• 远端地址可达性验证
• 现场排障与用户自助诊断

能力概览

当前推荐使用的 API 如下：

平台支持

插件可编译平台

按能力划分的支持情况

环境要求

• HBuilderX：5.07 或更高
• Android：minSdkVersion 24
• iOS：12.0 或更高
• Harmony：5.0.0 或更高

安装与引入

如果插件已经位于项目的 uni_modules/laoqianjunzi-net 目录中，页面中直接从插件根目录导入即可：

import {
  inspectReachability,
  readAdapterSnapshot,
  readLocalAddress,
  setTraceVerbosity,
  surveyLan
} from '@/uni_modules/laoqianjunzi-net'

注意事项：

• 请从 @/uni_modules/laoqianjunzi-net 导入，不要直接引用某个平台实现文件。
• 真机能力请优先用自定义基座或正式包验证，尤其是权限、局域网扫描和本机地址读取。
• Web 与小程序存在平台沙箱限制，README 中示例可运行不代表每个平台都能拿到相同粒度的数据。

快速开始

1. 打开调试日志

setTraceVerbosity('debug')

可选值：

• off：关闭日志
• debug：输出详细诊断日志

2. 探测目标是否可达

inspectReachability({
  target: 'www.baidu.com',
  attempts: 4,
  waitTimeout: 3000,
  payloadBytes: 32,
  success: (result) => {
    console.log('reachable', result.reachable)
    console.log('avgLatency', result.avgLatency)
    console.log('transcript', result.transcript)
  },
  fail: (error) => {
    console.error(error.errCode, error.errMsg, error.detail)
  }
})

3. 读取本机地址

readLocalAddress({
  preferIpv6: false,
  success: (result) => {
    console.log('preferredAddress', result.preferredAddress)
    console.log('ipv4List', result.ipv4List)
    console.log('ipv6List', result.ipv6List)
  }
})

4. 读取网卡快照

readAdapterSnapshot({
  success: (result) => {
    console.log('platform', result.platform)
    console.log('adapters', result.adapters)
  }
})

5. 扫描当前局域网

surveyLan({
  waitTimeout: 600,
  hostFrom: 1,
  hostTo: 32,
  success: (result) => {
    console.log('localAddress', result.localAddress)
    console.log('discoveredCount', result.discoveredCount)
    console.log('nodes', result.nodes)
  }
})

API 说明

setTraceVerbosity(level)

设置插件内部日志输出级别。

参数

使用建议

• 联调阶段可开启 debug
• 生产环境建议保持 off

inspectReachability(options)

探测目标连通性，返回是否可达、丢包率、时延统计与原始诊断文本。

请求参数

返回结果 ReachabilityReport

目标输入约束

以下情况会直接触发参数错误：

• 空字符串
• 含空格、换行
• 含 ;、&、| 等明显不安全字符

平台差异

• Android：基于系统探测能力，返回结果最接近传统网络诊断工具。
• iOS：IPv4 优先走 ICMP，其他情况可能回退到 TCP 握手探测，因此 payloadBytes 不一定在所有目标上生效。
• Harmony：使用原生探测实现，返回结构与 App 端保持一致。
• Web：本质是基于 uni.request 的 HTTP 请求探测，不是原生 ping，resolvedAddress 可能是请求 URL 而非实际 IP。
• 微信小程序：不支持该能力，会进入失败回调。

readLocalAddress(options)

读取当前设备的本机地址快照。

请求参数

返回结果 LocalAddressReport

结果说明

• 如果 preferredAddress 为空，通常表示当前设备没有拿到可用本机地址，或平台隐私策略阻止了枚举。
• Web 端依赖浏览器 RTCPeerConnection / ICE 候选信息，部分浏览器可能因为 mDNS 混淆、隐私策略或能力关闭而无法返回真实地址。
• 微信小程序不支持本机 IP 枚举。

readAdapterSnapshot(options)

读取网卡快照列表，适合用于诊断页或设备信息页。

请求参数

返回结果 AdapterSnapshotReport

AdapterSnapshot 字段

平台差异

• Android / iOS / Harmony：返回真实网卡快照。
• Web：基于 uni.getNetworkType 与本机地址推断，字段完整但信息粒度有限，wifiName 通常为空。
• 微信小程序：不支持。

surveyLan(options)

扫描当前设备所处的 IPv4 局域网网段，返回发现的在线节点。

请求参数

返回结果 LanSurveyReport

LanSurveyNode 字段

使用建议

• 建议先小范围扫描，例如 1-32、1-64，避免一次性探测整个网段导致页面等待过久。
• 该能力只面向当前 IPv4 网段，不做跨路由段发现。
• 如果当前设备没有可用 IPv4 地址，扫描会失败。

平台差异

• Android：支持局域网扫描，通常能拿到较完整的节点信息。
• iOS：支持局域网扫描，但由于系统沙箱限制，mac 字段通常为空。
• Harmony：支持局域网扫描。
• Web / 微信小程序：平台沙箱限制，不支持该能力。

错误处理

失败回调会返回 NetLabFailure：

错误码

建议：

• 页面展示给用户时使用 errMsg
• 排障日志中同时保留 errCode 与 detail
• 如果需要开发期定位，请同时展示结果中的 transcript

权限说明

插件已在模块侧声明所需权限，但业务侧仍应明确理解这些权限的用途，并在真机上完成验证。

Android

涉及权限：

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE
• android.permission.ACCESS_WIFI_STATE
• android.permission.READ_PHONE_STATE
• android.permission.ACCESS_FINE_LOCATION
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.NEARBY_WIFI_DEVICES（Android 13+）

说明：

• Wi-Fi 名称、网络介质、部分网络信息在 Android 上通常依赖位置或附近 Wi-Fi 相关授权。
• 若业务不使用相关展示能力，建议在产品与合规层面审慎评估权限申请范围。

iOS

涉及说明项：

• NSLocalNetworkUsageDescription
• NSCarrierUsageDescription

说明：

• 局域网扫描需要本地网络访问授权。
• 蜂窝网络代际标识依赖运营商网络信息能力。
• 获取 Wi-Fi 相关信息时，实际结果仍受系统权限、设备状态和 Apple 能力配置影响。

Harmony

涉及权限：

• ohos.permission.INTERNET
• ohos.permission.GET_NETWORK_INFO
• ohos.permission.GET_WIFI_INFO

使用建议

• 诊断页可以先调用 readLocalAddress，再调用 readAdapterSnapshot 与 inspectReachability，最后按需触发 surveyLan。
• 用户主动点击“开始诊断”时再触发局域网扫描，避免进入页面即执行重操作。
• Web 端建议把 inspectReachability 的结果文案解释为“请求连通性检测”，不要直接等同于系统 ping。
• 如果你需要现成示例页，可参考 uni_modules/laoqianjunzi-net/pages/index.uvue。

FAQ

1. 为什么 Web 端读不到本机 IP？

这是浏览器安全策略导致的常见现象。插件在 Web 端依赖 RTCPeerConnection / ICE 候选信息推断地址，部分浏览器会用 mDNS 混淆或直接屏蔽本机地址暴露。

2. 为什么局域网扫描结果里有些设备没有 MAC？

不同平台对 ARP、邻居表和网络接口信息的开放程度不同，尤其 iOS 沙箱限制更严格，因此 mac 字段可能为空。

3. 为什么目标明明能打开，但 inspectReachability 仍然失败？

可能原因包括：

• 目标禁止 ICMP 或短连接探测
• Web 端跨域、证书或请求超时导致失败
• 当前网络本身离线
• 域名能解析但目标端口策略不允许当前探测方式

建议结合 transcript 与 detail 一起分析。