更新记录

1.0.0（2026-09-11） 下载此版本

首发版本。

功能

• 对齐 uni 官方 WiFi 模块：startWifi / stopWifi / getConnectedWifi / onWifiConnected / offWifiConnected / getWifiList / onGetWifiList / offGetWifiList
• 增强超集：connectWifi（连接指定 WiFi）、disconnectWifi、getCurrentSSID
• Android + iOS 双平台
• getConnectedWifi 返回 WifiInfo：SSID / BSSID / secure / signalStrength / frequency
• getWifiList 返回 wifiList（含 SSID / BSSID / signalStrength / secure / frequency）
• connectWifi 同时兼容 uni 大写 SSID 与旧小写 ssid，并支持 options 回调与第二参 callback 两种调用（二者都会触发）
• errCode 对齐 jagger-wifi：0 成功 / 9010001 失败 / 9010002 连接后断开（仅 Android）
• 连接超时可配置：timeout（ms；Android 默认 12000，iOS 默认 20000）

平台实现

• Android：基于 WifiManager 连接/断开，startScan + SCAN_RESULTS_AVAILABLE_ACTION 获取扫描列表，NETWORK_STATE_CHANGED_ACTION 提供系统级连接事件
• iOS：基于 NEHotspotConfiguration 连接，NEHotspotNetwork.fetchCurrent 优先读取当前 SSID，回退 CNCopyCurrentNetworkInfo

修复与优化

• iOS：修复 connectWifi 的 timeout 参数被丢弃问题（options.timeout 已透传，并 clamp 到 20~90s）
• iOS：混编 Swift 数值参数统一使用 NSNumber，避免 NSNumber / Int 类型编译错误
• iOS：连接前做定位授权检查，notDetermined 时主动 requestWhenInUseAuthorization
• iOS：移除不可用的非公开 SPI（SecTaskCreateFromSelf / SecTaskCopyValueForEntitlement），改为解析 embedded.mobileprovision 自检 Access WiFi Information 能力
• iOS：优先使用 NEHotspotNetwork.fetchCurrent（旧 CNCopyCurrentNetworkInfo 在新系统常返回空），并增加上次结果缓存

文档

• README 增加平台能力矩阵，明确各 API 在 Android / iOS 的支持情况与降级行为
• 补充 iOS 接入配置（Hotspot Configuration / Access WiFi Information 能力、UTS.entitlements、Info.plist 权限说明）与 Android 权限说明
• 补充已知限制（系统 API 限制、ROM 差异、模拟器不支持等）

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lucis-wifi

对齐 uni 官方 WiFi 模块能力并补齐增强能力，Android + iOS 双端。

• 官方对齐：startWifi / stopWifi / getConnectedWifi / onWifiConnected / offWifiConnected / getWifiList / onGetWifiList / offGetWifiList
• 增强超集：connectWifi（连接指定 WiFi）/ disconnectWifi / getCurrentSSID

使用

import {
  connectWifi, disconnectWifi, getCurrentSSID,
  startWifi, stopWifi, getConnectedWifi,
  onWifiConnected, offWifiConnected,
  getWifiList, onGetWifiList, offGetWifiList
} from "@/uni_modules/lucis-wifi";

// 初始化（Android 建议先调用；iOS 空实现）
startWifi({ success: () => console.log("startWifi ok") });

// 连接（同时兼容 uni 大写 SSID 与旧小写 ssid）
connectWifi(
  {
    SSID: "MyWiFi",
    password: "12345678", // 开放网络可不传
    timeout: 25000,       // ms；Android 默认 12000，iOS 默认 20000 且 clamp 到 20~90s
    success: (res) => console.log("连接成功", res.ssid),
    fail: (res) => console.log("连接失败", res.errMsg)
  },
  // 也支持第二参 callback（两种都会触发）
  (res) => {
    // res.errCode: 0 成功 / 9010001 失败 / 9010002 连接后断开（仅 Android）
  }
);

// 当前连接详情（字段对齐 uni WifiInfo）
getConnectedWifi({
  success: (info) => console.log(info.SSID, info.BSSID, info.secure, info.signalStrength, info.frequency),
  fail: (err) => console.log("未连接或无权限", err.errMsg)
});

// 连接事件（Android 系统级；iOS 仅在 connectWifi 成功时触发一次）
onWifiConnected((info) => console.log("已连接", info.SSID));
offWifiConnected();

// WiFi 列表（仅 Android；iOS 固定 fail）
onGetWifiList((res) => console.log("共", res.wifiList.length, "个网络"));
getWifiList({ fail: (err) => console.log("不支持", err.errMsg) });
offGetWifiList();

// 断开（Android 断开当前连接；iOS 移除本插件为最近成功连接的 WiFi 添加的配置）
disconnectWifi();

// 同步查询当前 SSID
const ssid = getCurrentSSID(); // 未连接 / 无权限时返回 ""

// 释放
stopWifi();

平台能力矩阵

系统权限

Android

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
    android:usesPermissionFlags="neverForLocation" />

iOS（utssdk/app-ios/UTS.entitlements + Info.plist）

上述两个 Entitlement 需在 Apple Developer 为对应 bundle id 开启后才可用于打包；运行时系统会请求「定位（使用期间）」授权并弹出「允许加入 WiFi 网络」确认。

配置

iOS（打包前必须完成）

1. 在 Apple Developer 为 bundle id 开启：
   • Hotspot Configuration
   • Access WiFi Information
2. 本插件已内置 utssdk/app-ios/UTS.entitlements（含上述两个 capability）与 Info.plist（NSLocalNetworkUsageDescription + NSLocationWhenInUseUsageDescription），云端打包自动合并。
3. 连接时系统会依次弹出定位授权与「允许加入 WiFi 网络」确认，均需允许并保持 App 前台。
4. 模拟器无法读取 SSID；个人热点/系统限制场景也可能读不到。

Android

插件 utssdk/app-android/AndroidManifest.xml 已声明所需权限（WiFi 状态/修改、网络状态、精/粗定位、NEARBY_WIFI_DEVICES），打包自动合并，无需在 manifest.json 重复添加。

涉及原生代码/清单/能力配置，真机调试需重新制作自定义基座，发布需云端打包后生效。

已知限制

• Android 10+ 的 addNetwork/enableNetwork 已废弃，多数设备可用，部分国产 ROM / Android 14+ 可能受限
• Android 扫描列表（getWifiList）需要定位或 NEARBY_WIFI_DEVICES 权限，且部分 ROM 限制后台扫描频率
• iOS 只能管理由本 App 添加的热点配置，无法连接系统已保存但非本 App 添加的网络
• iOS 读取 SSID 依赖 Access WiFi Information + 定位授权；插件优先使用 NEHotspotNetwork.fetchCurrent，读不到时回退 CNCopyCurrentNetworkInfo
• 连接是否成功以系统状态为准，插件轮询仅做尽力判定