微信小程序WIFI API实战全解析：从权限配置到列表获取的完整避坑指南
1. 微信小程序WIFI API入门指南
第一次接触微信小程序的WIFI API时，我和大多数开发者一样，以为这不过是个简单的网络功能调用。但真正上手后才发现，从权限配置到列表获取，每个环节都藏着不少"坑"。记得当时为了获取WIFI列表，我整整调试了两天，最后才发现是位置权限配置出了问题。
微信小程序的WIFI API主要包含以下几个核心功能：
- 初始化/关闭WIFI模块
- 获取WIFI列表
- 连接指定WIFI
- 获取已连接WIFI信息
- 相关事件监听
这些API看起来简单，但实际使用时需要注意的细节很多。比如初始化顺序、权限配置、回调时机等，稍不注意就会导致功能无法正常使用。下面我会结合自己的踩坑经验，带你完整走一遍开发流程。
2. 权限配置避坑指南
2.1 必须配置的位置权限
最容易踩坑的就是权限问题。很多开发者（包括我）一开始都会忽略这个关键点：获取WIFI列表需要小程序位置权限，而不是微信的位置权限。这意味着你必须在app.json中明确声明：
"permission": { "scope.userLocation": { "desc": "需要获取您的位置信息以扫描附近WIFI" } }这个配置有两个关键点需要注意：
- desc字段的内容会显示在权限申请弹窗中，建议写得清晰易懂
- 即使配置了权限，用户仍然可能拒绝授权，所以代码中要做好错误处理
2.2 动态权限申请实战
配置静态权限只是第一步，实际开发中还需要处理动态权限申请：
// 检查权限状态 wx.getSetting({ success(res) { if (!res.authSetting['scope.userLocation']) { // 未授权时发起授权请求 wx.authorize({ scope: 'scope.userLocation', success() { console.log('授权成功') }, fail() { // 引导用户手动开启 wx.openSetting({ success(res) { console.log(res.authSetting) } }) } }) } } })这里有个常见问题：如果用户第一次拒绝授权，后续调用wx.authorize会直接失败。这时候必须通过wx.openSetting引导用户去设置页手动开启权限。
3. WIFI模块初始化与关闭
3.1 正确的初始化姿势
所有WIFI操作前必须先初始化模块：
wx.startWifi({ success(res) { console.log('WIFI模块初始化成功') // 这里可以开始其他WIFI操作 }, fail(err) { console.error('初始化失败', err) } })实测发现，初始化最好放在页面的onShow生命周期中，而不是onLoad。因为用户可能在离开页面后又返回，这时候需要重新初始化。
3.2 关闭模块的注意事项
使用完WIFI模块后，建议及时关闭释放资源：
wx.stopWifi({ success(res) { console.log('WIFI模块已关闭') } })但要注意，关闭模块会同时断开当前WIFI连接。如果需要在后台保持连接，就不要调用这个方法。
4. 获取WIFI列表的完整流程
4.1 监听与获取的时序问题
获取WIFI列表需要两个API配合使用：
// 先设置监听 wx.onGetWifiList(function(res) { console.log('获取到WIFI列表', res.wifiList) }) // 再主动获取 wx.getWifiList({ success(res) { console.log('触发获取WIFI列表') } })这里有个关键点：监听必须在获取之前设置，否则可能错过回调。我遇到过监听设置晚了导致列表为空的情况。
4.2 WIFI列表数据处理
获取到的WIFI列表数据包含以下关键字段：
{ wifiList: [{ SSID: 'wifi名称', BSSID: 'MAC地址', secure: true, // 是否需要密码 signalStrength: 80, // 信号强度 frequency: 2412 // 频率(MHz) }] }实际使用时建议对列表进行排序，比如按信号强度降序排列：
const sortedList = res.wifiList.sort((a, b) => b.signalStrength - a.signalStrength )5. WIFI连接与管理
5.1 连接指定WIFI
连接WIFI需要提供SSID和password：
wx.connectWifi({ SSID: 'your_wifi_name', password: 'your_password', success(res) { console.log('连接成功') }, fail(err) { console.error('连接失败', err) } })注意：在iOS设备上，系统会弹出原生WIFI连接确认框，用户需要手动确认。
5.2 监听连接状态
可以通过事件监听WIFI连接状态变化：
wx.onWifiConnected(function(res) { console.log('WIFI已连接', res.wifi) })这个回调在以下几种情况会触发：
- 手动调用wx.connectWifi成功时
- 设备自动连接到某个WIFI时
- 从无网络切换到有网络时
5.3 获取当前连接信息
除了监听事件，也可以主动查询：
wx.getConnectedWifi({ success(res) { console.log('当前连接信息', res.wifi) } })这个方法返回的数据结构与监听事件一致，适合在页面加载时获取初始状态。
6. 完整代码示例
下面是一个整合了所有功能的页面示例：
Page({ data: { wifiList: [], currentWifi: null }, onShow() { this.initWifi() }, initWifi() { wx.startWifi({ success: () => { this.setupListeners() this.checkPermission() } }) }, setupListeners() { wx.onGetWifiList(res => { this.setData({ wifiList: res.wifiList.sort((a, b) => b.signalStrength - a.signalStrength) }) }) wx.onWifiConnected(res => { this.setData({ currentWifi: res.wifi }) }) }, checkPermission() { wx.getSetting({ success: res => { if (res.authSetting['scope.userLocation']) { this.getWifiList() } else { wx.authorize({ scope: 'scope.userLocation', success: () => this.getWifiList(), fail: () => this.showPermissionGuide() }) } } }) }, getWifiList() { wx.getWifiList() }, connectWifi(SSID, password) { wx.connectWifi({ SSID, password }) }, onUnload() { wx.stopWifi() wx.offGetWifiList() wx.offWifiConnected() } })7. 常见问题排查
获取不到WIFI列表
- 检查位置权限是否授权
- 确认wx.onGetWifiList在wx.getWifiList之前调用
- 真机调试时确认手机WIFI功能已开启
连接WIFI失败
- 检查SSID和password是否正确
- iOS设备需要用户确认系统弹窗
- 某些企业级WIFI可能需要额外配置
监听事件不触发
- 确认没有重复设置监听（可能导致之前监听被覆盖）
- 检查是否在页面卸载时正确移除了监听
Android/iOS表现不一致
- iOS对WIFI相关API限制更多
- 部分Android机型可能需要特殊权限
- 测试时务必覆盖多款设备
开发过程中遇到问题时，建议先查阅微信官方文档，然后通过console.log逐步排查问题所在。WIFI功能对系统环境依赖较强，真机调试是必不可少的环节。