更新记录

0.1.0（2026-08-22）

• 实现 Android、iOS 的 DNS 解析和 TCP 端口连接诊断。
• 实现系统信任链 TLS 校验与叶子证书到期时间读取。
• 实现可选 HTTP HEAD 状态码、耗时和当前网络类型采集。
• 新增参数校验、结构化阶段错误、单任务并发控制和取消能力。
• 新增交互式链路仪表示例页、API 文档和双端真机测试清单。
• 通过 Android、iOS 插件模块及 uni-app x 整项目编译。
• 通过 iPhone 17 Pro / iOS 26.3 模拟器默认 HTTPS 目标完整诊断与界面验证。
• 示例页移除顶部 eyebrow 标识，整体调整为白色与浅灰绿视觉体系。
• 示例页可见标识与状态提示全部中文化，英文错误码仅保留在调试控制台中。
• 示例页默认折叠自定义网页请求地址，并根据诊断目标和端口自动生成请求地址。

平台兼容性

uni-app x(4.0)

xs-net-probe

面向 uni-app x App 的 DNS、TCP、TLS 与 HTTP 链路诊断 UTS API 插件。适合网络错误自检、客服排障页、服务可用性检查和环境信息采集。

支持平台

• Android 5.0（API 21）及以上。
• iOS 12.0 及以上。
• 已编译验证：uni-app x App-Android、App-iOS。
• Web、小程序和 HarmonyOS 暂不支持。

快速使用

import {
  runNetProbe,
  cancelNetProbe,
  NetProbeResult
} from '@/uni_modules/xs-net-probe'

runNetProbe({
  host: 'example.com',
  port: 443,
  url: 'https://example.com',
  timeoutMs: 5000
}, (result : NetProbeResult) => {
  console.log(result.resolvedAddresses, result.httpStatusCode, result.errors)
}, (error : string) => {
  console.error(error)
})

// 页面销毁或用户主动停止时调用
cancelNetProbe()

执行规则

• DNS 与 TCP 始终执行。
• 端口为 443 或 URL 使用 https:// 时执行 TLS。
• URL 非空时执行 HTTP HEAD 请求；URL 为空时 HTTP 字段为 null。
• timeoutMs 用于 TCP、TLS 与 HTTP 阶段，内部限制在 1000 至 60000 毫秒；Android DNS 也受该值限制，iOS DNS 使用系统解析器超时。
• 单阶段失败写入 errors，仍会返回其他已完成阶段的数据。
• 同一时刻只保留一次诊断；再次调用或执行 cancelNetProbe() 会取消旧任务并抑制其回调。

详细字段、错误码和示例见示例工程的 docs/API.md。

权限与隐私

• Android 自动合并 android.permission.INTERNET 和 android.permission.ACCESS_NETWORK_STATE，均无需运行时授权。
• iOS 无需申请用户授权权限。
• 插件仅连接调用方明确传入的目标，不内置上报地址，不存储、不上传结果。

能力边界

耗时是设备端观测值，包含系统调度和当前网络环境影响，不等同于服务端处理时间。HTTP 使用 HEAD，部分服务可能返回 405 等业务状态；只要取得状态码就视为 HTTP 阶段完成。明文 HTTP 是否允许由宿主应用安全策略决定。编译通过不代表所有运营商、代理、VPN、证书链和厂商系统都已完成真机兼容性验证。