Wi‑Fi 扫描、配网与连接踩坑,权限、扫描回调、密码错误、后台配网一次性讲透
先提一个很多 IoT 开发同学都会遇到的玄学问题:调用 Wi‑Fi 扫描接口,代码不报异常,但是扫描结果是空列表;或者扫描到了 Wi‑Fi,填好密码去连接,一直卡在连接中,没有明确报错;还有配网的时候 App 切后台,配网流程直接中断。
很多新手误区:Wi‑Fi 配网 = 扫描拿到热点列表 + 传入 SSID 和密码直接连接。 HarmonyOS 7 对 Wi‑Fi 子系统做了权限和能力拆分,扫描、连接、配网是互相独立的能力,而且增加了很多强限制:定位权限和 Wi‑Fi 扫描绑定、普通应用不能随意控制系统 Wi‑Fi 开关、后台配网有超时管控、部分加密类型热点校验逻辑收紧。老版本很多 “自动兜底” 的逻辑全部移除,坑点比想象多。
先分清几个核心概念,别搞混:
- Wi‑Fi 扫描:搜索周边 Wi‑Fi 热点,拿到 SSID、BSSID、加密方式、信号强度;鸿蒙 7 中,扫描必须搭配定位权限,没有定位权限扫描结果大概率为空
- 主动连接:知道 SSID + 密码,主动发起连接到指定 Wi‑Fi
- 配网(IoT 配网):设备处于待配网模式,设备先广播一个临时热点,App 连上这个临时热点,把家里 Wi‑Fi 的 SSID、密码传给设备,设备收到之后重启连家里路由器
吐槽一句:Wi‑Fi 相关的报错码真的很笼统!很多时候只返回一个通用失败标识,分不清是密码错误、加密方式不支持、信号太差,还是系统层面拒绝连接。而且鸿蒙 7 不允许 App 静默打开系统 Wi‑Fi 开关,必须引导用户手动去开启。
下面是适配 HarmonyOS7 可运行示例:包含 Wi‑Fi 扫描、连接、密码错误判断,同时标注权限配置。
import { wifiManager } from '@kit.ConnectivityKit';
// Wi-Fi热点信息结构
interface WifiItem {
ssid: string
bssid: string
securityType: wifiManager.WifiSecurityType
rssi: number
}
@Entry
@Component
struct WifiConfigPage {
@State tip: string = "等待扫描Wi-Fi"
@State wifiList: WifiItem[] = []
@State selectedSsid: string = ""
@State inputPwd: string = ""
private scanListenerId: number | null = null
aboutToDisappear() {
// 重点:页面销毁,注销扫描监听,防止内存泄漏
if (this.scanListenerId !== null) {
wifiManager.off('scanResultsChange', this.scanListenerId)
this.scanListenerId = null
}
}
// 1. 开始扫描周边Wi-Fi
async startScanWifi() {
this.tip = "正在扫描Wi-Fi..."
this.wifiList = []
try {
// 先判断系统Wi-Fi是否开启
const isWifiOpen = await wifiManager.isWifiActive()
if (!isWifiOpen) {
this.tip = "请先手动打开系统Wi-Fi开关!App无法自动开启Wi-Fi"
return
}
// 注册扫描结果监听
this.scanListenerId = wifiManager.on('scanResultsChange', (resultList) => {
const list: WifiItem[] = resultList.map(item => ({
ssid: item.ssid,
bssid: item.bssid,
securityType: item.securityType,
rssi: item.rssi
}))
// 去重:同一个SSID保留信号最强的一条
const map = new Map<string, WifiItem>()
list.forEach(item => {
const old = map.get(item.ssid)
if (!old || item.rssi > old.rssi) {
map.set(item.ssid, item)
}
})
this.wifiList = Array.from(map.values())
this.tip = `扫描完成,共找到 ${this.wifiList.length} 个热点`
})
// 发起扫描
await wifiManager.startScan()
} catch (err) {
this.tip = `扫描异常:${JSON.stringify(err)}`
}
}
// 2. 连接指定Wi-Fi
async connectWifi(ssid: string, pwd: string) {
try {
const config: wifiManager.WifiDeviceConfig = {
ssid: ssid,
preSharedKey: pwd,
securityType: wifiManager.WifiSecurityType.WPA2_PSK
}
const connectResult = await wifiManager.connect(config)
if (connectResult.isSuccess) {
this.tip = `成功发起连接:${ssid}`
} else {
// 这里是重点!鸿蒙7不会直接返回密码错误标记
this.tip = "连接失败,请检查密码、加密类型是否匹配"
}
} catch (err) {
this.tip = `连接请求异常:${JSON.stringify(err)}`
}
}
build() {
Column() {
Text(this.tip).fontSize(16).margin({ bottom: 16 })
Button("开始扫描Wi-Fi")
.onClick(() => this.startScanWifi())
.margin({ bottom: 12 })
if (this.wifiList.length > 0) {
Text("选择热点:")
Row() {
Select([{ value: item.ssid } for (item of this.wifiList)], {
value: this.selectedSsid,
onChange: (val: string) => {
this.selectedSsid = val
}
})
}.margin({ bottom: 12 })
TextInput({ text: this.inputPwd, placeholder: "输入Wi-Fi密码" })
.onChange((val: string) => this.inputPwd = val)
.margin({ bottom: 12 })
Button("连接选中Wi-Fi")
.onClick(() => {
if (!this.selectedSsid || !this.inputPwd) {
this.tip = "请选择热点并填写密码"
return
}
this.connectWifi(this.selectedSsid, this.inputPwd)
})
}
}.width('100%').padding(24)
}
}
module.json5 权限配置(必须加上)
"requestPermissions": [
{
"name": "ohos.permission.GET_WIFI_INFO",
"reason": "用于扫描周边Wi-Fi热点",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.LOCATION",
"reason": "Wi-Fi扫描依赖定位权限获取扫描结果",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
关键语句拆解
wifiManager.isWifiActive():判断系统 Wi‑Fi 开关状态。HarmonyOS7 禁止普通应用调用接口自动打开 Wi‑Fi,只能引导用户手动去系统设置开启,这是硬性限制。startScan():发起扫描,必须同时拥有GET_WIFI_INFO+ 定位权限,缺少定位权限,扫描回调大概率返回空数组。securityType加密类型:家庭路由器绝大多数是WPA2_PSK;部分新路由支持 WPA3;加密类型填错,就算密码正确也会连接失败。- 扫描监听
scanResultsChange:多次扫描会持续触发回调,页面销毁一定要调用off注销监听,不然会持续收到回调、内存上涨。 wifiManager.connect:只是发起连接请求,是异步动作,接口返回成功不等于已经连上 Wi‑Fi;如果要判断最终连接状态,需要额外监听网络状态变化。
HarmonyOS 7 高频踩坑清单
- ❌ 只申请 GET_WIFI_INFO,不申请定位权限 现象:调用 startScan 没有报错,但是扫描结果是空列表。 ✅ 方案:Wi‑Fi 扫描依赖定位权限,这是系统安全策略,鸿蒙 7 收紧之后比旧版本严格很多。
- ❌ 代码尝试自动打开系统 Wi‑Fi 现象:找不到对应的接口,或者调用直接返回失败。 ✅ 规范:App 不能静默打开 Wi‑Fi,只能弹窗引导用户手动开启 Wi‑Fi 开关。
- ❌ 加密类型写错,密码正确但是连接失败 比如路由器是 WPA3,代码写死 WPA2_PSK;或者老式 WEP 加密。 ✅ 方案:扫描结果里会返回热点真实的 securityType,连接的时候复用扫描拿到的加密类型,不要硬编码。
- ❌ 配网的时候 App 切后台,配网流程中断 IoT 配网场景,App 连上设备临时热点之后,如果切后台,系统会主动回收部分网络会话,导致发给设备的配网数据包丢失。 ✅ 方案:配网关键阶段提示用户保持 App 在前台;或者使用系统后台任务保活能力。
- ❌ 扫描不做去重,同一个 SSID 多条记录 同一个 SSID 可能有多个 BSSID(双频路由器 2.4G/5G),直接展示给用户会很迷惑,业务层根据信号强度做去重。
- ❌ 混淆【App 主动连接 Wi‑Fi】和【系统自动保存网络】 App 调用 connect 成功之后,系统不一定永久保存这个 Wi‑Fi 配置,部分设备重启之后不会自动重连。
- ❌ 5G 热点和 2.4G 热点混用配网 很多 IoT 设备只支持 2.4G Wi‑Fi,不支持 5G 频段!用户选择 5G 热点配网,会直接配网失败,这是 IoT 开发最高频的坑。 ✅ 方案:扫描结果里判断频段,只允许 2.4G 热点用于设备配网。
项目复盘总结
之前做 IoT 配网工具,最开始踩了两个大坑: 第一,只申请了 GET_WIFI_INFO,没有定位权限,测试机鸿蒙 7 上扫描一直是空列表,查文档才知道新版 Wi‑Fi 扫描绑定定位权限; 第二,用户经常选 5G Wi‑Fi 给设备配网,设备不支持 5G,一直提示配网失败。 后面加了频段判断,过滤掉 5G 热点,同时在 UI 提示用户 “请选择 2.4G Wi‑Fi”,这类工单大幅减少。 另外之前没有注销 scanResultsChange 监听,用户反复进出页面,监听不断叠加,引发大量重复回调、内存持续上涨,加上 aboutToDisappear 注销逻辑之后解决。
开发规范:
- Wi‑Fi 扫描:必须 GET_WIFI_INFO + 定位权限;
- App 不能自动开启 Wi‑Fi,引导用户手动开启;
- 连接热点加密类型优先从扫描结果读取,不要硬编码;
- IoT 配网一定要区分 2.4G/5G 频段;
- 扫描监听、网络监听,页面销毁及时 off 注销;
- 配网关键流程尽量引导用户保持 App 前台运行。

更多推荐


所有评论(0)