Uniapp跨平台WiFi状态检测：从基础获取到实时监听

1. 为什么你的Uniapp应用需要WiFi状态检测？

想象一下这个场景：你开发了一个公司内部的考勤打卡应用，员工到了公司，连上指定的办公WiFi，手机自动完成打卡。听起来很酷对吧？但现实是，如果应用不知道用户当前连的是哪个WiFi，或者连没连WiFi，这个功能就完全失效了。又或者，你正在做一个智能家居控制App，需要确保手机和智能硬件（比如智能灯泡、空调）在同一个局域网（WiFi）下才能进行本地控制，这时候检测WiFi连接状态和具体的网络信息就成了刚需。

这就是我们今天要聊的核心：在Uniapp里，如何准确、可靠地获取和监听设备的WiFi状态。这不仅仅是调用一个API那么简单，它涉及到不同手机系统（Android和iOS）的巨大差异、复杂的权限申请流程，以及如何从“一次性获取”升级到“实时监听”的进阶玩法。很多新手开发者，包括我早期也踩过不少坑，比如在iOS上死活获取不到WiFi名，或者在安卓某些机型上权限弹窗不出现，导致功能直接“罢工”。

所以，这篇文章我会把我这些年趟过的路、踩过的坑，用最直白的方式分享给你。我们不只讲uni.getNetworkType和uni.onNetworkStatusChange这两个核心API怎么用，更会深入它们背后的平台限制和实战技巧。目标是让你看完就能动手，写出的代码在真机上跑得稳稳的。

2. 基础入门：快速获取当前网络类型

让我们先从最简单、最基础的一步开始：判断设备当前是否在线，以及连接的是哪种网络。Uniapp提供了一个非常友好的API：uni.getNetworkType。这个接口属于“网络”模块，不需要额外配置，开箱即用。

2.1 认识 uni.getNetworkType

你可以把uni.getNetworkType理解成一个网络状态“快照”。它在你调用它的那一刻，去问系统：“嘿，哥们儿，现在网络啥情况？”系统会立刻告诉你结果。它的返回值是一个对象，里面最重要的属性就是networkType。

这个networkType可能是以下几种值之一：

• wifi：设备正在通过WiFi联网。
• 2g、3g、4g、5g：设备正在使用蜂窝移动网络（就是流量）。
• unknown：未知网络，这种情况比较少见。
• none：设备处于离线状态，没有任何网络连接。

它的用法简单到令人发指，几行代码就能搞定：

uni.getNetworkType({ success: (res) => { console.log('当前网络类型：', res.networkType); if (res.networkType === 'wifi') { uni.showToast({ title: '已连接WiFi，可以开始操作了！', icon: 'none' }); // 这里可以执行需要WiFi环境的功能，比如连接本地服务器 } else if (res.networkType === 'none') { uni.showToast({ title: '网络已断开，请检查连接', icon: 'none' }); } else { uni.showToast({ title: '当前使用的是移动网络，请注意流量', icon: 'none' }); } }, fail: (err) => { console.error('获取网络类型失败：', err); } });

看到没？就这么简单。你可以在应用启动时调用它，或者在用户点击某个需要网络的功能按钮前调用它，做一个前置检查。这对于需要区分“WiFi环境”和“流量环境”的应用场景非常有用，比如视频App在WiFi下自动播放高清，在流量下播放标清。

2.2 基础方法的局限性

但是，uni.getNetworkType有一个天生的“短板”：它只能告诉你调用瞬间的状态。网络是动态变化的，用户可能在你调用完API、判断为WiFi后，下一秒就关闭了WiFi开关。这时候你的应用还傻傻地以为自己在WiFi环境下，继续执行那些需要局域网的操作，结果就是一连串的失败和糟糕的用户体验。

我举个真实的例子。之前做一个本地文件上传功能，要求必须在公司WiFi下才能上传到内网服务器。我用getNetworkType在点击上传按钮时做了检查，一切正常。但测试同事发现，如果在点击“上传”后、上传完成前，手机WiFi断了（比如走出路由器范围），应用就会卡住，直到网络超时，没有任何提示。用户完全不知道发生了什么。

所以，uni.getNetworkType适合用于对实时性要求不高的、一次性的状态检查。如果你的业务场景是“网络状态一变，我就要立刻知道并做出反应”，那这个基础方法就力不从心了。这就需要我们请出更强大的工具：网络状态变化监听。

3. 核心进阶：实时监听网络状态变化

如果说uni.getNetworkType是拍一张照片，那uni.onNetworkStatusChange就是安装了一个24小时不间断的监控摄像头。只要网络状态一有风吹草动，它就会立刻通知你。这对于需要动态响应网络变化的场景来说，是必不可少的。

3.1 掌握 uni.onNetworkStatusChange

这个API的使用模式是“监听”。你只需要在应用启动的某个时机（比如在App.vue的onLaunch里，或者某个主要页面的onLoad里）设置一次监听器，之后无论网络怎么变，你的回调函数都会被自动触发。

// 设置网络状态变化监听 uni.onNetworkStatusChange((res) => { console.log('网络状态发生变化：', res); // res.isConnected 表示是否有网络连接（boolean） // res.networkType 表示当前的网络类型（string） if (!res.isConnected) { uni.showToast({ title: '网络已断开，请检查您的网络设置', icon: 'none' }); // 可以在这里暂停视频播放、停止数据同步等耗网络的操作 } else if (res.networkType === 'wifi') { uni.showToast({ title: '已切换到WiFi网络', icon: 'none' }); // 可以在这里恢复高清播放、开始大文件下载或连接本地服务 } else { uni.showToast({ title: '正在使用移动网络，请注意流量消耗', icon: 'none' }); // 可以在这里切换为省流模式，暂停后台自动更新 } }); // 注意：监听器是全局的，通常只需要设置一次。 // 在页面卸载时，可以使用 uni.offNetworkStatusChange 来移除监听，避免内存泄漏。

实测下来，这个监听非常灵敏。无论是从WiFi切换到蜂窝数据，还是直接打开飞行模式，回调都能在1秒内触发。你可以利用这个特性做很多体验优化：比如在断网时自动显示一个友好的提示层，在恢复WiFi时自动重试之前失败的操作，或者在切换到流量时弹出二次确认框，防止用户误操作消耗大量流量。

3.2 组合拳：基础获取 + 实时监听的最佳实践

在实际项目中，我推荐你将两者结合使用，形成一个“组合拳”。这套策略我用了很多次，非常稳。

策略思路：

1. 应用启动/页面加载时，先用uni.getNetworkType获取当前初始状态。你不能等网络变了才知道初始状态，对吧？一开始就要知道用户处在什么网络环境下，以便正确初始化界面和功能。
2. 紧接着，立即调用uni.onNetworkStatusChange设置监听。这样就能保证从这一刻起，任何网络变化都逃不过你的“法眼”。
3. 在监听回调里，根据最新的res.networkType来更新应用内部的一个全局状态（比如Vuex里的state）。让所有组件都能基于这个单一、准确的数据源来工作。

下面是一个在Vue页面中实现的简单示例：

// 在页面的 data 或 Vuex state 中定义一个状态 data() { return { currentNetworkType: 'unknown', isConnected: false } }, onLoad() { // 步骤1：获取初始状态 this.getCurrentNetwork(); // 步骤2：设置变化监听 this.listenNetworkChange(); }, methods: { getCurrentNetwork() { uni.getNetworkType({ success: (res) => { this.currentNetworkType = res.networkType; this.isConnected = res.networkType !== 'none'; console.log('初始网络状态：', this.currentNetworkType); } }); }, listenNetworkChange() { uni.onNetworkStatusChange((res) => { console.log('网络状态变化：', res); this.currentNetworkType = res.networkType; this.isConnected = res.isConnected; // 这里可以根据变化执行具体的业务逻辑 this.handleNetworkChange(res); }); }, handleNetworkChange(status) { // 你的具体业务逻辑，例如： if (status.networkType === 'wifi') { this.startSyncData(); // 开始同步数据 } else if (!status.isConnected) { this.pauseAllDownloads(); // 暂停所有下载 } } }

这套组合拳打下来，你的应用对网络状态的感知就既全面又及时了。但是，到这里我们解决的还只是“有没有网”、“是什么网”的问题。对于很多智能硬件连接、公司内网应用来说，光知道是WiFi还不够，我们还得知道具体连接的是哪个WiFi（SSID）。这才是真正让人头疼的地方，因为Android和iOS在这里走上了两条完全不同的路。

4. 深入实战：获取具体WiFi信息（SSID/BSSID）与平台大坑

获取当前连接的WiFi名称（SSID）和路由器MAC地址（BSSID），是很多高级功能的基础。比如文章开头说的“连接指定WiFi自动打卡”，或者“只允许在家庭WiFi下控制智能插座”。Uniapp提供了uni.getConnectedWifi这个API，但它的使用绝非一帆风顺，平台差异巨大。

4.1 Android平台：相对“友好”但需权限

在Android上，获取已连接的WiFi信息，理论上是可行的。但你需要跨越两道主要的关卡：定位权限和WiFi权限。

第一关：精确定位权限。从Android 10（API 29）开始，谷歌出于隐私考虑，将WiFi SSID/BSSID等信息归类为“精确定位”信息。这意味着，你的应用要想读取这些信息，必须获得用户授予的ACCESS_FINE_LOCATION权限。是的，你没看错，获取WiFi信息需要定位权限，这听起来有点奇怪，但规则就是这样。

在Uniapp的manifest.json文件中，你需要配置这个权限：

// manifest.json -> app-plus -> distribute -> android { "permissions": [ "android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_WIFI_STATE", "android.permission.CHANGE_WIFI_STATE" // 如果需要操作WiFi，比如扫描 ] }

配置好了还不够，你必须在代码中动态向用户申请授权。Uniapp提供了uni.authorize和uni.getSetting来帮你完成这个流程。我强烈建议你封装一个权限请求函数，逻辑如下：

1. 用uni.getSetting检查用户是否已经授权过定位权限。
2. 如果没授权，用uni.authorize发起授权弹窗。
3. 如果用户拒绝，需要引导用户手动去系统设置页打开权限（使用uni.openSetting）。

第二关：WiFi状态初始化。在调用uni.getConnectedWifi之前，必须先调用uni.startWifi初始化WiFi模块。这个步骤在Android上是必须的，在iOS上则不需要（但调用也无害）。我建议把初始化放在应用启动或需要用到WiFi功能的页面加载时。

一个比较完整的Android端获取流程代码结构如下：

// 假设在某个页面或工具函数中 async function getAndroidWifiInfo() { // 1. 检查并申请定位权限（这里省略了详细的权限申请逻辑，建议封装成独立函数） const locationAuth = await checkAndRequestLocationPermission(); if (!locationAuth) { uni.showToast({ title: '需要定位权限才能获取WiFi信息', icon: 'none' }); return; } // 2. 初始化WiFi模块 uni.startWifi({ success: () => { console.log('WiFi模块初始化成功'); // 3. 获取已连接的WiFi信息 uni.getConnectedWifi({ success: (wifiRes) => { console.log('连接到的WiFi信息：', wifiRes.wifi); const ssid = wifiRes.wifi.SSID; // WiFi名称 const bssid = wifiRes.wifi.BSSID; // 路由器MAC地址 // 接下来就可以用ssid和你预设的WiFi名进行比对，实现业务逻辑 }, fail: (err) => { console.error('获取连接WiFi失败：', err); // 可能的原因：没连接WiFi、权限不足、初始化未完成 uni.showToast({ title: '获取WiFi信息失败', icon: 'none' }); } }); }, fail: (err) => { console.error('WiFi模块初始化失败：', err); } }); }

4.2 iOS平台：限制重重，巧用“已信任”网络

如果说Android是“持证上岗”就能干活，那iOS简直就是“此路不通”。由于苹果极其严格的隐私政策，在标准的iOS SDK中，应用无法直接获取当前连接的WiFi的SSID和BSSID。从iOS 13开始，这个限制变得更加严格。你调用uni.getConnectedWifi，在iOS上大概率会直接失败。

那是不是就无解了呢？也不是，苹果留了一个“后门”，但这个后门有前提条件：你的应用必须拥有“已配置WiFi网络”的权限，并且用户当前连接的WiFi，必须是你的应用曾经配置过的。

这听起来很绕，我解释一下。这个能力主要设计给“运营商App”或“智能硬件配网App”使用的。比如，你有一个智能摄像头，需要手机App帮它配置家里的WiFi密码。流程通常是：

1. 摄像头进入配网模式，发出一个特定的WiFi热点。
2. 手机连接这个摄像头热点。
3. 在App里，你可以调用相关API（如uni.addWifi，注意这需要额外原生插件或特定模块支持，非Uniapp标准API）获取到手机当前连接的WiFi列表（此时是摄像头热点），并让用户选择其家庭WiFi，输入密码。
4. App将这些配置信息发送给摄像头，摄像头自己去连接家庭WiFi。

在这个过程中，App“知道”了家庭WiFi的SSID和密码。如果未来用户手机连接的就是这个家庭WiFi，App在获得相应权限（Hotspot Configuration能力，需要在苹果开发者后台配置）的情况下，是能识别出来的。

所以，对于大多数普通的、只是想验证用户是否连接了某个指定WiFi的应用（比如打卡），在iOS上，直接获取SSID这条路基本走不通。

4.3 跨平台适配策略与降级方案

面对Android和iOS的巨大差异，我们必须设计一套聪明的、有弹性的适配策略。不能因为iOS限制多就放弃这个功能。

我的实战策略是这样的：

1. 首先进行平台判断。使用uni.getSystemInfoSync().platform来判断当前是Android还是iOS。

2. 分平台处理：

   • Android端：走完整的“权限申请 -> 初始化 -> 获取WiFi信息”流程。拿到SSID后，与后台配置的合法WiFi名称进行比对。
   • iOS端：直接放弃获取SSID。采用降级方案。

3. iOS降级方案推荐：

   • 方案A：依赖网络类型+额外验证。我们虽然拿不到SSID，但uni.getNetworkType和uni.onNetworkStatusChange在iOS上是可以正常工作的，能准确知道是否连接了WiFi。我们可以结合其他信息来“间接”验证。例如，在连接WiFi的前提下，让用户点击一下“打卡”按钮，App同时获取设备的IP地址局域网段（通过uni.getLocalIPAddress，注意这也是扩展API）和粗略地理位置（需要用户授权，精度较低，如城市级别）。将IP段和地理位置信息上传到服务器，由服务器根据公司网络部署情况做一个综合判断。虽然不如SSID精准，但结合业务逻辑，能很大程度上防止作弊。
   • 方案B：使用企业证书或特定场景。如果你的应用是面向企业内部员工分发（使用企业证书签名），或者有特殊合作渠道，可以尝试申请使用苹果的NEHotspotConfiguration相关API，但这需要额外的原生开发，超出了标准Uniapp的能力范围。
   • 方案C：引导用户手动选择。在无法自动检测时，提供一个列表让用户自己选择“我当前连接的WiFi是哪一个”。当然，这体验上打了折扣。

下面是一个简单的平台适配代码示例：

// 获取连接WiFi信息的适配函数 function getWifiConnectionInfo() { const platform = uni.getSystemInfoSync().platform; if (platform === 'android') { // 调用上述的Android完整流程 return getAndroidWifiInfo(); } else if (platform === 'ios') { // iOS降级处理 console.log('iOS平台，采用降级方案'); uni.showModal({ title: '提示', content: '在iOS上，为了更好的隐私保护，我们无法直接获取WiFi名称。请确保您已连接到指定网络，或使用其他验证方式。', showCancel: false }); // 这里可以触发方案A或方案C的逻辑 // 例如，尝试获取本地IP // uni.getLocalIPAddress({ ... }); return Promise.resolve({ platform: 'ios', ssid: 'unavailable' }); } else { console.log('其他平台'); return Promise.reject(new Error('Unsupported platform')); } }

记住，在移动开发中，优雅降级比硬性阻塞更重要。我们的目标是保证核心功能可用，同时在条件允许时提供更佳的体验。

5. 权限申请：绕不开的复杂流程与用户体验

无论是Android的定位权限，还是iOS可能需要的网络权限，权限申请都是WiFi状态检测功能里用户体验的关键一环。处理不好，用户一脸懵，直接拒绝，你的功能就废了。

5.1 设计友好的权限申请流程

不要一上来就弹窗要权限。用户会想：“我就要打个卡，你为什么要知道我在哪儿？” 这会导致很高的拒绝率。

正确的姿势是：解释 -> 触发 -> 引导。

1. 解释（Explanation）：在需要权限的功能入口处，先用一个自定义的弹窗或页面文字，向用户解释为什么需要这个权限。例如：“为了确保您在公司范围内打卡，我们需要获取WiFi网络信息，这需要您授予位置权限（用于Android手机识别WiFi）。我们承诺仅用于打卡验证，不会追踪您的具体位置。”
2. 触发（Trigger）：在用户点击“我明白了”或相关操作按钮后，再调用系统的权限申请API（uni.authorize）。这时用户有了心理预期，授权率会高很多。
3. 引导（Guidance）：如果用户还是点了“拒绝”，不要就此放弃。应该再次弹窗，更清晰地说明没有这个权限功能无法使用，并提供一个按钮，引导用户跳转到系统的应用设置页面（uni.openSetting）去手动开启权限。

这里有一个权限工具函数的伪代码思路，你可以把它封装成模块：

// permissionHelper.js export const requestLocationPermissionForWifi = () => { return new Promise((resolve, reject) => { // 1. 首先检查是否已有权限 uni.getSetting({ success: (res) => { if (res.authSetting['scope.userLocation'] === true) { // 已有权限 resolve(true); } else if (res.authSetting['scope.userLocation'] === false) { // 已被拒绝，需要引导去设置页 showGuideToSettingsModal().then(resolve).catch(reject); } else { // 从未询问过，先解释再申请 showExplanationModal().then(() => { uni.authorize({ scope: 'scope.userLocation', success: () => resolve(true), fail: () => { // 用户拒绝授权 showGuideToSettingsModal().then(resolve).catch(reject); } }); }).catch(reject); } }, fail: (err) => reject(err) }); }); }; // 显示解释性弹窗 function showExplanationModal() { return new Promise((resolve, reject) => { uni.showModal({ title: '需要您的位置权限', content: '此功能需要获取WiFi信息以验证打卡位置。在Android系统上，这需要您授予“位置信息”权限。我们仅用于网络识别，不会记录您的行踪。', confirmText: '去授权', cancelText: '取消', success: (res) => { if (res.confirm) { resolve(); } else { reject(new Error('用户取消授权')); } } }); }); } // 显示引导去设置的弹窗（类似，略）

5.2 权限状态管理与持久化

你还需要在应用内部管理权限状态。比如，用户第一次拒绝后，你引导他去了设置页，他可能当时没开，过一会儿又开了。或者他直接在系统设置里关闭了权限。所以，不能只在应用启动时检查一次权限。

一个好的做法是，在每次执行需要权限的敏感操作（如调用getConnectedWifi）之前，都检查一下当前权限状态。或者，利用uni.onNetworkStatusChange这类全局监听，在关键节点进行权限复核。把权限状态存到Vuex或全局变量里，供各个组件查询。

6. 完整实战案例：构建一个WiFi环境感知的智能组件

光说不练假把式。最后，我们把这些知识点串起来，构建一个在Uniapp中可复用的、智能的“网络状态感知器”组件。这个组件会：

1. 自动获取初始网络状态。
2. 实时监听网络变化。
3. 在Android上，尝试获取精确的WiFi信息（SSID）。
4. 在iOS上，采用降级方案。
5. 对外提供一个统一的、简单易用的状态接口。

由于代码较长，我在这里勾勒出核心结构和思路：

1. 创建状态管理（Vuex Store）创建一个Vuex模块，用于集中管理网络状态。

// store/modules/network.js export default { state: { isConnected: false, networkType: 'unknown', wifiSSID: null, // 当前连接的WiFi SSID (Android可能获取到) platform: 'unknown' }, mutations: { updateNetworkStatus(state, payload) { Object.assign(state, payload); } }, actions: { async initNetworkListener({ commit, dispatch }) { const sysInfo = uni.getSystemInfoSync(); commit('updateNetworkStatus', { platform: sysInfo.platform }); // 1. 获取初始状态 const initialStatus = await dispatch('getCurrentNetwork'); commit('updateNetworkStatus', initialStatus); // 2. 设置监听 uni.onNetworkStatusChange((res) => { commit('updateNetworkStatus', { isConnected: res.isConnected, networkType: res.networkType }); // 网络变化时，如果是WiFi且是Android，尝试重新获取SSID if (res.networkType === 'wifi' && sysInfo.platform === 'android') { dispatch('fetchWifiSSID'); } else { commit('updateNetworkStatus', { wifiSSID: null }); } }); // 3. 如果是Android且初始就是WiFi，获取SSID if (initialStatus.networkType === 'wifi' && sysInfo.platform === 'android') { dispatch('fetchWifiSSID'); } }, // 其他 actions: getCurrentNetwork, fetchWifiSSID, requestPermissions... } };

2. 在应用入口初始化在App.vue的onLaunch中，派发初始化动作。

// App.vue onLaunch() { this.$store.dispatch('network/initNetworkListener'); }

3. 在业务页面中使用在任何需要感知网络的页面，通过计算属性或mapState来获取状态，并做出响应。

<template> <view> <text>当前网络：{{ networkType }}</text> <text v-if="wifiSSID">连接WiFi：{{ wifiSSID }}</text> <button @click="handleCheckIn" :disabled="!canCheckIn">打卡</button> </view> </template> <script> import { mapState } from 'vuex'; export default { computed: { ...mapState('network', ['isConnected', 'networkType', 'wifiSSID']), canCheckIn() { // 业务逻辑：在WiFi环境下，并且对于Android，SSID需要匹配公司WiFi const isWifi = this.networkType === 'wifi'; const isCorrectWifi = this.platform !== 'android' || this.wifiSSID === 'Company-WiFi-Name'; return isWifi && isCorrectWifi; } }, methods: { handleCheckIn() { if (!this.canCheckIn) { uni.showToast({ title: '请连接到指定的公司WiFi网络', icon: 'none' }); return; } // 执行打卡API... } } }; </script>

这个组件框架把复杂的权限、平台判断、状态监听都封装在了Vuex层，业务页面只需要关心“当前是什么状态”和“根据状态能做什么”，代码清晰，维护起来也方便。

7. 避坑指南与调试技巧

开发过程中，我遇到了无数个坑，这里挑几个最常见的分享给你，希望能帮你节省时间。

坑1：Android模拟器上获取不到WiFi信息。很多模拟器（尤其是Android Studio自带的AVD）的WiFi模块是模拟的或者不完整，getConnectedWifi可能返回空或失败。真机调试是必须的。如果条件有限，可以尝试在startWifi成功后，先调用uni.getWifiList看看是否能扫描到附近的WiFi，这有助于判断是否是权限或初始化问题。

坑2：iOS真机调试时，权限弹窗不出现。检查Xcode中的工程配置（如果用了自定义基座或原生插件）。确保在Info.plist中添加了对应的权限描述字段，例如获取位置权限需要NSLocationWhenInUseUsageDescription。如果是云打包，记得在Uniapp开发者中心的“App模块配置”和“App权限配置”中勾选和填写相应内容。

坑3：监听函数被多次触发。如果你在多个页面组件的onLoad里都写了uni.onNetworkStatusChange，那么网络变化一次，回调会被执行多次。记住，这是一个全局监听。最佳实践是在根组件（如App.vue）或状态管理库中只设置一次，并通过状态分发来通知各个页面。

调试技巧：

• 善用console.log：在每个关键步骤（权限检查结果、API调用成功/失败）都打印日志，能快速定位问题出在哪一环。
• 查看系统日志：在HBuilderX的真机运行控制台，或者使用Android Studio的Logcat、Xcode的Console，可以查看更底层的系统日志，有时能发现权限被拒绝的具体原因。
• 分平台编译调试：开发时，可以分别编译Android和iOS版本到真机，隔离平台特定问题。

WiFi状态检测这个功能，说简单也简单，几个API调用；说复杂也复杂，涉及到平台差异、隐私权限和用户体验的平衡。我的经验是，永远不要假设用户的网络环境是稳定和理想的，代码里要多做判断，多考虑异常情况。把这次分享的这些点都注意到，你的Uniapp应用在网络感知这一块，基本就能做到既强大又稳健了。