更新记录

0.1.0（2026-08-18）

• 实现 Android 系统代理、VPN、网络类型和连接状态检测。
• 实现 iOS 系统代理、虚拟隧道和网络类型检测。
• 新增统一风险结果与网络变化监听，重复状态不重复回调。
• 修复 iOS 变化监听在部分运行环境中只回调首次结果的问题。
• 新增交互式示例页、API 文档和双端真机测试清单。
• 通过 Android、iOS 模块编译和 uni-app x 整项目编译。
• 通过 Android 真机核心功能验证，代理、VPN、网络状态及变化监听运行正常。

平台兼容性

uni-app x(4.0)

xs-net-guard

面向 uni-app x App 的代理、VPN 与网络风险环境检测 UTS API 插件。所有检测均在设备本地完成，不联网、不存储、不上传数据。

支持平台

• Android 5.0（API 21）及以上。
• iOS 12.0 及以上。
• 已编译验证：uni-app x App-Android、App-iOS。
• 已真机验证：App-Android 的代理、VPN、网络状态与变化监听核心功能。
• Web、小程序和 HarmonyOS 暂不支持。

快速使用

import {
  getNetworkRisk,
  startNetworkRiskMonitor,
  stopNetworkRiskMonitor,
  NetworkRiskResult
} from '@/uni_modules/xs-net-guard'

const current = getNetworkRisk()
console.log(current.riskLevel, current.reasons)

startNetworkRiskMonitor((result : NetworkRiskResult) => {
  console.log('网络风险变化', result)
})

// 页面销毁或不再需要监听时调用
stopNetworkRiskMonitor()

API

• checkProxy()：返回当前系统代理的开关、类型、主机和端口。
• checkVPN()：返回是否发现活跃 VPN 网络。
• getNetworkRisk()：返回代理、VPN、网络类型、连接状态、风险等级及原因。
• startNetworkRiskMonitor(callback)：立即回调一次结果，并在代理、VPN或网络类型变化时回调。
• stopNetworkRiskMonitor()：停止原生网络监听和轮询。

详细字段和规则见示例工程的 docs/API.md。

权限与数据

• Android 自动合并 android.permission.ACCESS_NETWORK_STATE，无需运行时授权。
• iOS 无需申请用户授权权限。
• 插件只读取本机网络状态，不访问业务请求内容，也不会上传检测结果。

调试基座

插件包含 Android 权限清单和 iOS 系统框架配置。HBuilderX 标准基座不能应用项目新增的原生配置，真机联调时请制作自定义调试基座。

能力边界

代理或 VPN 是网络环境信号，不等同于恶意行为。iOS 的 VPN 检测使用活跃虚拟网卡名称特征，Private Relay、企业网络或部分系统服务可能产生类似接口。请将检测结果用于提示、二次验证或风控加权，不要作为封禁用户的唯一依据。本插件不能阻止抓包，也不能检测所有应用内代理、自定义隧道或已越狱/Root 环境中的规避手段。