更新记录

1.0.0（2026-09-13）

• 新增 HarmonyOS 支持：EspTouch V1 / V2（含 AES 加密）、SoftAP、getCurrentWifi。
• 兼容传统 uni-app（vue2 / vue3，Android / iOS / HarmonyOS）。
• API 变更：getCurrentWifi 改为通过回调返回 WifiInfo | null。
• EspTouch V2 默认超时改为 90 秒；显式传入 timeoutMs 时以传入值为准。
• 修复 iOS 配网在部分网络环境下持续超时、终态不回调的问题。
• 修复停止配网后旧回调仍可能触发的问题；修复日志开关不生效的问题。
• 日志不再输出 WiFi 密码。
• 示例页改为手动发起配网。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

hans-esp-provision

为用乐鑫芯片（ESP32 / ESP32-C3 / ESP8266 等）做智能硬件、用 uni-app x 或传统 uni-app（vue2 / vue3）写配套 App 的开发者提供 WiFi 配网能力。

• EspTouch V1（一键配网 / SmartConfig，UDP 包长编码，广播模式）
• EspTouch V2（可选 AES 加密 + 自定义附加数据）
• SoftAP 热点配网（检测设备热点连接 → TCP 下发凭据 → 回包确认）
• 当前 WiFi 信息读取（getCurrentWifi，供配网表单预填）

平台支持

框架支持：uni-app x 与传统 uni-app（vue2 / vue3）均可用 App 平台（Android/iOS/HarmonyOS）。

插件自带全部原生依赖，无需手工配置；鸿蒙端无三方原生依赖。iOS 广播模式 EspTouch 需要开通组播网络能力的 provisioning profile（见下方「安装与配置」），若证书不含组播权限，优先使用 SoftAP。

安装与配置

1. HBuilderX 4.61+（HarmonyOS 目标建议 5.24+）；插件导入后 Android 权限、iOS Info.plist/entitlements、鸿蒙 module.json5 权限会随云打包/自定义基座自动合并，无需手工拷贝（鸿蒙端权限均为系统授权，无弹窗）。
2. 必须打自定义基座（含原生 jar/framework），标准调试基座无法运行本插件。
3. iOS 侧需要：
   • 定位权限（读 SSID）——插件已声明用途描述；
   • 本地网络权限（iOS 14+ 弹窗）；
   • Access WiFi Information entitlement（插件已声明 com.apple.developer.networking.wifi-info，需在证书/profile 中同步勾选）；
   • 广播模式 EspTouch 需要含组播网络权限的 profile。
4. Android 侧权限：INTERNET、ACCESS_NETWORK_STATE、ACCESS_WIFI_STATE、CHANGE_WIFI_STATE、CHANGE_WIFI_MULTICAST_STATE、ACCESS_FINE_LOCATION、NEARBY_WIFI_DEVICES(12+)。

快速上手（uni-app x）

import { startProvisioning, stopProvisioning, getCurrentWifi } from '@/uni_modules/hans-esp-provision'
import { EspProvisionEvent, EspProvisionOptions, ProvisionMode, WifiInfo } from '@/uni_modules/hans-esp-provision'

// 异步预填当前 WiFi（三端 API 一致）
getCurrentWifi((wifi: WifiInfo | null) => {
  if (wifi != null) console.log('当前 WiFi: ' + wifi!.ssid)
})

// options 显式声明类型，mode 字面量用 as 标注（uni-app x 编译器对内联对象字面量
// 和字面量联合的推导不稳，统一用声明式写法，三端编译一致）
const options: EspProvisionOptions = {
  mode: 'esptouch_v1' as ProvisionMode,
  ssid: 'MyRouter',
  password: 'pwd12345',
  timeoutMs: 60000
}

startProvisioning(options, (event: EspProvisionEvent) => {
  if (event.state == 'success') {
    console.log('设备 IP: ' + (event.result?.ip ?? ''))
  } else if (event.state == 'fail') {
    console.log('失败 ' + event.errCode + ': ' + (event.errMsg ?? ''))
  } else {
    console.log('进度: ' + event.state) // scanning | provisioning
  }
})

// 用户取消
stopProvisioning()

传统 uni-app（vue2 / vue3）用法一致：导入路径相同，页面 JS 里去掉类型标注与 as 断言即可（options 与回调事件是同结构的普通对象；页面用 ts 则可保留标注）。

EspTouch V2（AES 可选）：

const options: EspProvisionOptions = {
  mode: 'esptouch_v2' as ProvisionMode,
  ssid: 'MyRouter',
  password: 'pwd12345',
  aesKey: '0123456789abcdef',
  reservedData: ''
}
startProvisioning(options, (event: EspProvisionEvent) => {
  // 同上
})

SoftAP：提示用户连接设备热点后调用；插件按 deviceApPrefix（默认 esp32，contains 忽略大小写）校验当前 SSID，并向 192.168.4.1:8266 下发凭据。

SoftAP 固件契约

设备热点网关 192.168.4.1 TCP 8266：

• App → 设备：一行 JSON {"ssid":"...","password":"..."}\n
• 设备 → App：一行 JSON {"ok":true,"ip":"192.168.x.x"}\n（ip 可选；拒绝时 ok:false）

API

EspProvisionOptions：mode（'esptouch_v1' | 'esptouch_v2' | 'softap' | 'ble'）、ssid、password、bssid?、deviceApPrefix?、deviceApPassword?、timeoutMs?（V2 默认 90000，其它模式默认 60000）、taskCount?(默认 1)、aesKey?（16 字节 UTF-8，仅 v2）、reservedData?（≤64 字节，仅 v2）。

EspProvisionEvent：state（'scanning' | 'provisioning' | 'success' | 'fail'）+ 终态附带 result（ip/bssid/elapsedMs）或 errCode/errMsg。

错误码

已知边界与排障

• EspTouch V1/V2 只能配 2.4G 网络；WPA3-only 路由器大概率失败（v1 协议边界），建议路由器开 WPA2 兼容。
• iOS 读不到 SSID：检查定位权限（设置里为"使用期间"）、profile 是否含 Access WiFi Information、是否真机（模拟器无 WiFi 信息）。
• V1/V2 超时：确认设备已进入配网模式、手机与设备在同一 2.4G 路由器、路由器未开 AP 隔离。
• 鸿蒙端：App 切后台期间配网定时器被系统挂起，回前台恢复（表现为配网耗时变长）；手机重启或刚安装后约 3 分钟内 UDP bind 可能失败（返回 9021099 并附原因，数分钟后自愈）。
• 蓝牙（BLE）辅助配网为 v1.x 规划能力，当前调用返回 9021001。

异步读取与会话取消

getCurrentWifi(callback) 使用回调返回结果，兼容传统 uni-app iOS 真机异步桥接。iOS 侧读取不阻塞主线程；需要允许使用期间定位、开启精确位置，并在签名中包含 Access WiFi Information。

配网会等待 WiFi 查询再启动任务，iOS 的 timeoutMs 包括这段等待时间。WiFi 信息不可读返回 9021007；只有确认当前 SSID 不匹配设备热点时才返回 SoftAP 9021020。stopProvisioning() 会使待返回的查询和旧会话事件失效；终态回调内可以立即启动下一轮。一次调用的进度与终态通过同一个持续回调交付。