保姆级教程：用uni-app开发小程序WiFi连接功能（附iOS权限配置避坑指南）
从零构建uni-app小程序WiFi连接功能：iOS权限配置与实战避坑指南
在智能硬件和物联网应用蓬勃发展的当下，小程序连接WiFi功能已成为智能家居控制、设备配网等场景的刚需。uni-app作为跨平台开发框架，让开发者可以用一套代码同时发布到微信、支付宝等多个小程序平台，但当涉及WiFi等系统级功能时，不同平台尤其是iOS系统的特殊限制常常让开发者措手不及。本文将带您从零开始，避开那些官方文档没明说的"坑"，特别是iOS 13+系统下定位权限与WiFi信息获取的复杂关系，以及苹果开发者后台那令人困惑的"Access WiFi information"配置项。
1. 开发环境准备与插件配置
工欲善其事，必先利其器。在开始编码前，我们需要确保开发环境满足uni-app WiFi功能的最低要求。与常规uni-app开发不同，WiFi功能需要特定的HBuilderX版本和扩展插件支持。
首先确认您的HBuilderX版本不低于3.6.8——这个版本开始才支持uni-ext-api，这是调用原生WiFi功能的基础。升级方法很简单：点击HBuilderX菜单栏的"帮助"→"检查更新"，按照提示完成升级即可。
接下来需要安装uni-WiFi插件。这个官方维护的插件封装了各平台的原生WiFi API，让我们可以用统一的JavaScript接口调用WiFi功能。安装步骤：
- 打开HBuilderX插件市场（快捷键Ctrl+P/Cmd+P）
- 搜索"uni-WiFi"或直接访问插件页面
- 点击"使用HBuilderX导入插件"按钮
安装完成后，需要在项目的manifest.json中声明WiFi权限。找到"App模块配置"选项卡，勾选"WiFi"模块。这个步骤经常被忽略，导致后续调用API时出现"permission denied"错误。
// manifest.json 部分配置 "permission": { "request": { "scope.userLocation": { "desc": "获取WiFi信息需要定位权限" } } }对于iOS平台，还需要额外配置隐私描述。在manifest.json的"iOS"→"privacyDescription"节点下添加：
"NSLocationWhenInUseUsageDescription": "连接WiFi需要获取您的位置信息", "NSLocationAlwaysUsageDescription": "连接WiFi需要获取您的位置信息"这些描述文字会显示在系统权限弹窗中，直接影响用户授权率，建议用清晰易懂的语言说明权限用途。
2. iOS特殊配置：开发者后台的隐藏关卡
iOS平台对用户隐私的保护近乎苛刻，这导致WiFi功能实现比Android复杂得多。从iOS 13开始，苹果将WiFi信息视为敏感的位置数据，因此需要两个关键配置才能正常获取WiFi信息。
2.1 开启Access WiFi Information能力
这个配置项藏得很深，却是iOS WiFi功能能否正常工作的决定性因素。操作流程如下：
- 登录Apple Developer账号，进入"Certificates, Identifiers & Profiles"
- 选择"Identifiers"，找到您的小程序对应的App ID
- 在"Capabilities"列表中，找到"Access WiFi Information"并勾选
- 保存后重新生成Provisioning Profile文件
这里有个常见陷阱：修改App ID配置后，必须重新生成Provisioning Profile并下载安装到开发环境，否则修改不会生效。很多开发者在这里踩坑，花费数小时排查为什么代码没问题但功能就是不工作。
2.2 处理iOS 13+的定位权限问题
从iOS 13开始，获取已连接WiFi的SSID和BSSID信息需要定位权限。这意味着即使用户只是想查看当前连接的WiFi名称，您的应用也需要请求位置权限。这个设计让很多用户困惑，也增加了开发复杂度。
在实际编码中，我们需要先检查定位权限状态，再尝试获取WiFi信息。以下是推荐的处理流程：
async function checkAndRequestLocationPermission() { return new Promise((resolve) => { uni.authorize({ scope: 'scope.userLocation', success: () => resolve(true), fail: () => { uni.showModal({ title: '需要位置权限', content: '连接WiFi需要您授予位置权限', success: (res) => { if (res.confirm) { uni.openSetting({ success: (res) => { resolve(res.authSetting['scope.userLocation'] === true) } }) } } }) } }) }) }注意iOS系统对权限弹窗的显示有严格限制——如果用户已经拒绝过权限请求，再次调用authorize会直接失败，必须引导用户手动前往设置页开启权限。良好的用户体验应该是在首次被拒时，就优雅地解释为什么需要这个权限，并提供跳转设置的快捷方式。
3. WiFi功能核心实现与平台差异处理
有了前面的基础配置，我们现在可以着手实现WiFi连接的核心功能了。uni-app的WiFi API主要包括以下几个关键方法：
uni.startWifi()：初始化WiFi模块uni.stopWifi()：关闭WiFi模块（节省电量)uni.getConnectedWifi()：获取当前连接WiFi信息uni.getWifiList()：获取周围WiFi列表uni.connectWifi()：连接指定WiFi
3.1 初始化与基础状态管理
WiFi功能使用前必须初始化，这看似简单却隐藏着平台差异。Android平台初始化几乎是瞬时的，而iOS可能需要几百毫秒的准备时间。最佳实践是使用异步方式初始化：
async function initWifiModule() { try { await new Promise((resolve, reject) => { uni.startWifi({ success: resolve, fail: reject }) }) console.log('WiFi模块初始化成功') return true } catch (error) { console.error('WiFi模块初始化失败:', error) uni.showToast({ title: 'WiFi功能不可用', icon: 'none' }) return false } }3.2 获取WiFi列表的平台适配
获取周围WiFi列表是功能的核心，但Android和iOS的实现机制完全不同。Android可以直接获取到详细的WiFi列表，包括信号强度、加密类型等信息；而iOS由于隐私限制，只能获取到SSID(网络名称)和BSSID(物理地址)，且需要用户已经授予定位权限。
更复杂的是，在公共场所经常会遇到多个同名WiFi热点(比如多个"Starbucks"接入点)。我们需要对这些结果进行智能合并：
function processWifiList(rawList) { // 按信号强度过滤重复SSID const wifiMap = new Map() rawList.forEach(item => { if (!wifiMap.has(item.SSID) || item.signalStrength > wifiMap.get(item.SSID).signalStrength) { wifiMap.set(item.SSID, item) } }) return Array.from(wifiMap.values()) .sort((a, b) => b.signalStrength - a.signalStrength) }3.3 连接WiFi的健壮性实现
连接WiFi看似简单，实则有很多边界情况需要考虑：密码错误、信号太弱、认证方式不支持等。以下是一个健壮的连接实现：
async function connectToWifi(ssid, password) { return new Promise((resolve) => { const connectTimeout = setTimeout(() => { uni.showToast({ title: '连接超时', icon: 'none' }) resolve(false) }, 30000) // 30秒超时 uni.connectWifi({ SSID: ssid, password: password, success: () => { clearTimeout(connectTimeout) uni.onWifiConnected((res) => { if (res.wifi.SSID === ssid) { resolve(true) } }) }, fail: (err) => { clearTimeout(connectTimeout) let errMsg = '连接失败' if (err.errCode === 12002) { errMsg = '密码错误' } else if (err.errCode === 12003) { errMsg = '连接超时' } uni.showToast({ title: errMsg, icon: 'none' }) resolve(false) } }) }) }4. 调试技巧与上架注意事项
即使代码完美，实际运行中仍可能遇到各种意外情况。掌握有效的调试方法可以节省大量排查时间。
4.1 真机调试的必备技巧
WiFi功能必须在真机上测试，模拟器无法模拟真实WiFi环境。调试时建议：
- 准备多个不同iOS版本的测试设备（至少覆盖iOS 13和最新版）
- 测试各种网络环境（家庭WiFi、企业网络、公共热点）
- 模拟弱网环境（使用网络限速工具）
iOS调试有个特别有用的技巧：在Xcode的设备日志中过滤"WiFi"关键字，可以查看详细的WiFi子系统日志，这对排查权限问题特别有帮助。
4.2 上架App Store的合规检查
苹果对涉及WiFi和定位功能的应用审核严格，确保您的应用：
- 在元数据中明确说明WiFi功能的用途
- 不要尝试获取或存储用户的位置数据
- 隐私政策中说明WiFi和定位数据的使用方式
- 确保"Access WiFi Information"能力已正确开启
常见被拒理由包括"未提供足够的隐私说明"和"功能与描述不符"。提前准备详细的说明文档可以避免审核延误。
4.3 性能优化与电量管理
WiFi扫描是耗电操作，在实现时需要注意：
- 避免频繁扫描（间隔不低于30秒）
- 在后台时停止WiFi模块
- 使用缓存机制减少重复扫描
// 页面隐藏时释放资源 onHide() { uni.stopWifi() this.wifiList = [] }5. 进阶功能与用户体验优化
基础功能实现后，我们可以进一步优化用户体验，增加实用功能。
5.1 自动连接已知网络
对于需要频繁连接固定网络的场景（如智能家居设备），可以实现自动连接：
const KNOWN_NETWORKS = [ { ssid: 'HomeWiFi', password: '12345678' }, { ssid: 'OfficeWiFi', password: 'company123' } ] async function autoConnectKnownNetworks() { const { wifi } = await getConnectedWifi() if (wifi && KNOWN_NETWORKS.some(n => n.ssid === wifi.SSID)) { return // 已经连接到已知网络 } const list = await scanWifiNetworks() for (const network of KNOWN_NETWORKS) { if (list.some(item => item.SSID === network.ssid)) { const success = await connectToWifi(network.ssid, network.password) if (success) break } } }5.2 信号强度可视化
用直观的方式显示WiFi信号强度可以提升用户体验：
<view class="wifi-item" v-for="item in wifiList" :key="item.BSSID"> <text>{{ item.SSID }}</text> <view class="signal-strength"> <view v-for="i in 4" :key="i" :class="['bar', i <= signalBars(item.signalStrength) ? 'active' : '']"> </view> </view> </view>function signalBars(rssi) { if (rssi >= -50) return 4 // 强信号 if (rssi >= -60) return 3 if (rssi >= -70) return 2 return 1 // 弱信号 }5.3 记住网络功能
对于需要频繁输入密码的WiFi网络，可以实现安全的密码存储：
// 使用uni-app的secureStorage保存敏感信息 async function saveWifiPassword(ssid, password) { try { await uni.setStorage({ key: `wifi_pwd_${ssid}`, data: password, encrypt: true // 启用加密存储 }) } catch (error) { console.error('保存密码失败:', error) } }