先提一个很多 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"
    }
  }
]

关键语句拆解

  1. wifiManager.isWifiActive():判断系统 Wi‑Fi 开关状态。HarmonyOS7 禁止普通应用调用接口自动打开 Wi‑Fi,只能引导用户手动去系统设置开启,这是硬性限制。
  2. startScan():发起扫描,必须同时拥有 GET_WIFI_INFO + 定位权限,缺少定位权限,扫描回调大概率返回空数组。
  3. securityType 加密类型:家庭路由器绝大多数是 WPA2_PSK;部分新路由支持 WPA3;加密类型填错,就算密码正确也会连接失败。
  4. 扫描监听 scanResultsChange:多次扫描会持续触发回调,页面销毁一定要调用 off 注销监听,不然会持续收到回调、内存上涨。
  5. wifiManager.connect:只是发起连接请求,是异步动作,接口返回成功不等于已经连上 Wi‑Fi;如果要判断最终连接状态,需要额外监听网络状态变化。

HarmonyOS 7 高频踩坑清单

  1. ❌ 只申请 GET_WIFI_INFO,不申请定位权限 现象:调用 startScan 没有报错,但是扫描结果是空列表。 ✅ 方案:Wi‑Fi 扫描依赖定位权限,这是系统安全策略,鸿蒙 7 收紧之后比旧版本严格很多。
  2. ❌ 代码尝试自动打开系统 Wi‑Fi 现象:找不到对应的接口,或者调用直接返回失败。 ✅ 规范:App 不能静默打开 Wi‑Fi,只能弹窗引导用户手动开启 Wi‑Fi 开关。
  3. ❌ 加密类型写错,密码正确但是连接失败 比如路由器是 WPA3,代码写死 WPA2_PSK;或者老式 WEP 加密。 ✅ 方案:扫描结果里会返回热点真实的 securityType,连接的时候复用扫描拿到的加密类型,不要硬编码。
  4. ❌ 配网的时候 App 切后台,配网流程中断 IoT 配网场景,App 连上设备临时热点之后,如果切后台,系统会主动回收部分网络会话,导致发给设备的配网数据包丢失。 ✅ 方案:配网关键阶段提示用户保持 App 在前台;或者使用系统后台任务保活能力。
  5. ❌ 扫描不做去重,同一个 SSID 多条记录 同一个 SSID 可能有多个 BSSID(双频路由器 2.4G/5G),直接展示给用户会很迷惑,业务层根据信号强度做去重。
  6. ❌ 混淆【App 主动连接 Wi‑Fi】和【系统自动保存网络】 App 调用 connect 成功之后,系统不一定永久保存这个 Wi‑Fi 配置,部分设备重启之后不会自动重连。
  7. ❌ 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 前台运行。
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐