更新记录

1.0.2（2026-07-27）

• 更新配置文件

1.0.1（2026-07-27）

• 更新配置文件

1.0.0（2026-07-27）

• 支持 Android/iOS 连接指定 SSID，支持开放、WEP、WPA2 和 WPA3 能力映射。
• 支持当前 Wi-Fi、状态监听、连接监听、配置列表、移除配置和系统设置入口。
• Android 支持附近 Wi-Fi 扫描、列表监听与扫描缓存状态。
• Android 10+ 使用 WifiNetworkSpecifier，Android 9 及以下使用 WifiConfiguration。
• iOS 使用 NEHotspotConfigurationManager，明确处理系统不开放的扫描和 Wi-Fi 开关能力。

平台兼容性

uni-app(3.7.11)

uni-app x(3.7.11)

s-wifi 原生 Wi-Fi 管理插件

s-wifi 是面向 App Android 和 App iOS 的 UTS 原生插件，提供指定 SSID 连接、当前网络查询、状态监听、配置管理、Android 附近网络扫描和系统设置入口。

本插件必须制作自定义调试基座并使用真机运行。模拟器不能验证真实 Wi-Fi 连接。

平台能力

运行时可调用 getWifiCapabilities() 获取准确的平台能力，不要仅根据平台名称控制界面。

安装

1. 从插件市场导入，确认项目存在 uni_modules/s-wifi。
2. 按下文配置 Android 权限和 iOS Capability。
3. 在 HBuilderX 中制作包含本插件的自定义调试基座。
4. 使用 Android/iPhone 真机运行。

Android 配置

插件原生清单已声明：

• ACCESS_WIFI_STATE
• CHANGE_WIFI_STATE
• ACCESS_NETWORK_STATE
• CHANGE_NETWORK_STATE
• ACCESS_FINE_LOCATION
• NEARBY_WIFI_DEVICES（Android 13+）

调用扫描、当前网络或连接前，推荐先调用：

requestWifiPermissions({
  requestLocation: true,
  success(result) {
    console.log(result.granted, result.locationServiceEnabled)
  },
})

Android 6+ 扫描附近 Wi-Fi 需要精确位置权限；多数版本还要求系统定位服务处于开启状态。插件不读取 GPS 坐标，但 Android 将 Wi-Fi 扫描结果视为可推断位置的数据，应用隐私政策必须如实说明。

Android 会限制扫描频率。WifiListResult.updated 为 false 表示本次返回的是系统缓存，不等于调用失败。重复扫描建议间隔至少 30 秒。

iOS 配置

Capability

在 Apple Developer 的 App ID Capability 中开启：

• 开启 Access Wi-Fi Information
• 开启 Hotspot

连接指定 SSID 必须启用 Hotspot Configuration：

<key>com.apple.developer.networking.HotspotConfiguration</key>
<true/>

读取当前 SSID/BSSID 建议同时启用 Access WiFi Information：

<key>com.apple.developer.networking.wifi-info</key>
<true/>

在 manifest.json 中可配置：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSLocationWhenInUseUsageDescription": "用于识别当前连接的 Wi-Fi，帮助完成设备配网"
        },
        "capabilities": {
          "entitlements": {
            "com.apple.developer.networking.HotspotConfiguration": true,
            "com.apple.developer.networking.wifi-info": true
          }
        }
      }
    }
  }
}

Hotspot Configuration 和 Access WiFi Information 不需要向 Apple 单独申请特殊权限。手动签名时，修改 App ID Capability 后必须重新生成 Provisioning Profile。

如果业务要请求定位权限，还必须配置 NSLocationWhenInUseUsageDescription。只连接指定 SSID、不读取当前网络时，可调用 requestWifiPermissions({ requestLocation: false })，但不同 iOS 版本下的当前 SSID 查询仍可能返回不可用。

iOS 普通应用不能扫描附近 SSID。startWifiScan() 和 getWifiList() 会返回 1600001，不要使用私有 API 或依赖需要 Apple 特批的 NEHotspotHelper。

快速开始

import {
  connectWifi,
  getCurrentWifi,
  initializeWifi,
  onWifiConnectionStateChange,
  onWifiStateChange,
  requestWifiPermissions,
} from '@/uni_modules/s-wifi'

onWifiStateChange(state => {
  console.log('Wi-Fi 状态', state)
})

onWifiConnectionStateChange(event => {
  console.log('连接变化', event.ssid, event.connected, event.reason)
})

initializeWifi({
  success() {
    requestWifiPermissions({
      requestLocation: true,
      success() {
        connectWifi({
          ssid: 'DEVICE_AP',
          password: '12345678',
          security: 'wpa2',
          timeout: 30000,
          bindProcess: true,
          success(result) {
            console.log('连接成功', result)
          },
          fail(error) {
            console.error(error.errCode, error.errMsg)
          },
        })
      },
    })
  },
})

getCurrentWifi({
  success(result) {
    console.log(result.wifi.ssid, result.wifi.ipAddress)
  },
})

调用约定

普通方法采用与 uni API 一致的回调结构：

失败对象包含 errSubject: 's-wifi'、errCode、errMsg，与指定网络相关的错误还可能包含 ssid。

初始化与能力

initializeWifi(options)

初始化原生管理器并启动 Wi-Fi 状态监听。除 getWifiCapabilities() 和 openWifiSettings() 外，其他方法应在初始化成功后调用。

closeWifi(options)

停止扫描和监听、取消插件维护的网络请求并释放原生资源。Android 10+ 如果设置了 bindProcess: true，关闭时会解除进程网络绑定。

getWifiCapabilities(options)

返回 WifiCapabilities：

requestWifiPermissions(options)

Android 13+ 同时处理 NEARBY_WIFI_DEVICES。iOS 的热点连接 Capability 不是运行时权限，本方法只处理可选的定位授权。

getWifiState(options)

返回 WifiState：available、enabled、connected、monitoring、locationServiceEnabled 和 ssid。

iOS 不开放 Wi-Fi 硬件开关状态，因此 enabled 表示当前网络路径正在使用 Wi-Fi，而不是系统设置中的开关值。

扫描与列表

startWifiScan(options)

仅 Android 支持。

扫描结果通过 onWifiListChange() 返回。

stopWifiScan(options)

停止插件的重复扫描调度。Android 已提交给系统的单次扫描无法取消，其结果仍可能到达。

getWifiList(options)

仅 Android 支持附近列表。

返回 wifiList、updated 和 timestamp。每个 WifiNetwork 包含：

• ssid、bssid
• secure、security、capabilities
• RSSI、signalLevel
• frequency、channel
• hidden、isConnected、timestamp

连接与断开

connectWifi(options)

Android 10+ 使用 WifiNetworkSpecifier。对于没有互联网的智能硬件热点，bindProcess: true 可确保业务网络请求走设备 Wi-Fi；断开或 closeWifi() 时插件会解除绑定。

Android 10+ 不支持通过本插件连接 WEP。Android 9 及以下不支持 WPA3。企业级 802.1X/EAP 暂不属于本插件的连接范围。

disconnectWifi(options)

平台限制：

• Android 9 及以下可断开当前网络；只有显式传入 removeConfiguration: true 才会删除配置。
• Android 10+ 只能释放本插件通过 WifiNetworkSpecifier 发起的网络请求，不能强制断开用户在系统设置中连接的网络。
• iOS 只能移除本 App 创建且仍存在的 NEHotspotConfiguration。系统可能继续保持连接，因此请检查结果的 disconnected。

getCurrentWifi(options)

返回 CurrentWifi。Android 还会尽量提供 networkId、linkSpeed、IP、子网掩码、网关和 DNS。iOS 不公开的字段使用空字符串、0 或 -1，不会伪造数值。

配置与系统设置

getConfiguredWifiList(options)

返回 ssids：Android 9 及以下为应用可读的系统配置，iOS 为本 App 通过 NEHotspotConfigurationManager 创建的配置。Android 10+ 返回 1600015。

removeWifiConfiguration(options)

传入必填 ssid，移除应用有权管理的配置。Android 10+ 不能删除系统保存网络；iOS 不能删除其他 App 或用户创建的配置。

setWifiEnabled(options)

传入 enabled。仅 Android 9 及以下支持，其他系统返回 1600015。

openWifiSettings(options)

Android 打开系统 Wi-Fi 设置；iOS 只能使用公开 API 打开当前 App 的设置页，不能直接跳转到 Wi-Fi 设置页。

事件监听

onWifiStateChange(callback)
offWifiStateChange(callback?)

onWifiListChange(callback)
offWifiListChange(callback?)

onWifiConnectionStateChange(callback)
offWifiConnectionStateChange(callback?)

不传 callback 调用 off... 会清空对应类型的全部监听器。页面卸载时应移除页面注册的监听器；仅在整个业务不再使用 Wi-Fi 时调用 closeWifi()。

WifiConnectionStateChange 包含 ssid、bssid、connected、reason、status 和 timestamp。事件用于刷新界面，关键业务仍应通过 getCurrentWifi() 再确认当前状态。

错误码

发布与审核建议

• 连接动作应由用户明确触发，不要在启动时自动弹出系统确认。
• App Store 审核说明中写明连接 Wi-Fi 的具体用途，例如智能硬件配网。
• Android 隐私政策应解释 Wi-Fi 扫描和位置权限用途。
• 不要宣称 iOS 可以扫描附近网络、读取密码或静默切换任意 Wi-Fi。
• 真机至少覆盖 Android 9、Android 10/11、Android 13+ 和 iOS 15+。