设备 Wi-Fi 配网总失败一份可脚本化的排查清单一、密码明明对了却配网失败去年帮一个连锁客户做门店监控实施同事在群里连发三张图机身二维码、路由器贴纸、App 报错「添加失败」。店长站在旁边问「是不是你们摄像机坏了」我远程让他做一件事在开发者后台调「未绑定设备信息」接口把返回里的wifiConfigMode、wifiTransferMode截图发来——三十秒就定位了机型只支持2.4GHz 声波配网现场手机连的是5G Wi-Fi还强行走了SmartConfig。换 2.4G 频段、改声波配网第四遍成功。密码从未错模式和频段错了。二、配网、上线、绑定是三件事很多工单把「配网失败」和「绑定失败」写在一起技术上是两条链路阶段完成标志常见接口/动作配网设备连上目标 Wi-Fi能访问互联网App / OpenSDKSmartConfig、SoftAP、声波等上线平台侧status为 online轮询「未绑定设备信息」或分页查详情绑定设备进入开发者资产池bindDevice 正确code┌─ SmartConfig / SoftAP / 声波 … 手机 ────┤ └─ 把 SSID密码交给设备 │ ▼ 设备连 Wi-Fi 上网 │ ▼ unBindDeviceInfo.status online │ ▼ bindDevice验证码/密码 │ ▼ listDeviceDetailsByPage 能查到且 onlineOpenAPI 不会替你发 Wi-Fi 广播——配网动作在客户端 SDK 或官方 App完成HTTP 接口负责查能力、查状态、绑定、换热点。集成商要把分工写进 SOP避免后端同学被拉去「写配网协议」。配网模式速查接口字段wifiConfigMode平台「未绑定设备信息」接口会返回设备支持的模式多值逗号分隔常见如下模式适用现场注意SmartConfig一键传 Wi-Fi 密码手机需近场Android 常要定位权限2.4GSoftAP设备开热点手机连上去配先连设备 AP再回路由器 SSIDSoundWave声波传密码环境别太吵音量要够LAN有线网线直插无无线步骤QRCode扫码传参按机型说明扫特定码另有wifiTransferMode不少 IPC 仅2.4Ghz。门店 5G 优先、双频合一的 SSID是现场失败排名第一的原因。架构谁干什么开发者 OpenAPI现场SmartConfig/SoftAPonline实施 App / OpenSDKIPC 待配网unBindDeviceInfobindDevicelistDeviceDetailsByPagecurrentDeviceWifi / wifiAround三、四层排查 代码0. 公共调用壳全文复用// lib/platform-call.js — 网关域名、appId、appSecret 放环境变量importcryptofromnode:crypto;import{randomUUID}fromnode:crypto;exportfunctioncalcSign(time,nonce,appSecret){constrawtime:${time},nonce:${nonce},appSecret:${appSecret};returncrypto.createHash(md5).update(raw,utf8).digest(hex);}exportasyncfunctionplatformCall(method,params{}){constappIdprocess.env.APP_ID;constappSecretprocess.env.APP_SECRET;constbaseprocess.env.OPENAPI_BASE;// 文档中的区域网关 /openapiconsttimeMath.floor(Date.now()/1000);constnoncerandomUUID();constbody{system:{ver:1.0,appId,sign:calcSign(time,nonce,appSecret),time,nonce},id:randomUUID(),params,};constresawaitfetch(${base}/${method},{method:POST,headers:{Content-Type:application/json},body:JSON.stringify(body),});constjsonawaitres.json();if(json.result?.code!0)thrownewError([${json.result.code}]${json.result.msg});returnjson.result.data;}exportasyncfunctionadminToken(){constdataawaitplatformCall(accessToken,{});returndata.accessToken;}第一层配网前 — 查能力别盲试先调「未绑定设备信息」再决定 App 里点哪种配网方式// scripts/01-preflight.jsimportdotenv/config;import{platformCall,adminToken}from../lib/platform-call.js;constdeviceIdprocess.env.TARGET_DEVICE_ID;consttokenawaitadminToken();constinfoawaitplatformCall(unBindDeviceInfo,{token,deviceId,// 扫码可得可选deviceCodeModel, deviceModelName, ncCode});console.log({support:info.support,deviceExist:info.deviceExist,status:info.status,bindStatus:info.bindStatus,wifiConfigMode:info.wifiConfigMode,wifiConfigModeOptional:info.wifiConfigModeOptional,wifiTransferMode:info.wifiTransferMode,catalog:info.catalog,});决策表贴实施手册返回值动作deviceExist: notExist核对序列号、是否假机/未烧录support: false机型不在平台支持列表bindStatus已绑定勿重复配网走解绑或换账号wifiTransferMode仅 2.4Ghz路由器必须开 2.4G勿只连 5GwifiConfigMode含 SoftAPSmartConfig 失败时改 SoftAP踩坑 1不查wifiConfigMode全系门店用 SmartConfig——声波机型成功率能差五倍以上。第二层配网中 — SDK 流程要点HTTP 不能替代配网但实施 App 里建议固定顺序与常见 OpenSDK 文档一致SmartConfig 路径1. unBindDeviceInfo → 确认未绑定、支持 SmartConfig 2. 手机连 2.4G Wi-Fi与目标 SSID 同频段 3. SDK 发起无线配对传入 SSID / 密码 4. 局域网搜索设备 / 轮询 status 直到 online 5. bindDeviceSoftAP 路径1. unBindDeviceInfo → 确认支持 SoftAP 2. 手机连接设备热点机身标签有 SSID 提示 3. SDK SoftAP 配对下发家里路由器密码 4. 手机切回正常 Wi-Fi轮询 online 5. bindDeviceAndroid 权限清单缺一项可能「永远配网中」!-- 配网常见所需权限按 SDK 文档裁剪 --uses-permissionandroid:nameandroid.permission.INTERNET/uses-permissionandroid:nameandroid.permission.ACCESS_WIFI_STATE/uses-permissionandroid:nameandroid.permission.CHANGE_WIFI_STATE/uses-permissionandroid:nameandroid.permission.ACCESS_FINE_LOCATION/uses-permissionandroid:nameandroid.permission.ACCESS_COARSE_LOCATION/踩坑 2Android 10 未开定位SmartConfig静默失败——界面还在转圈log 里没有任何异常。踩坑 3双频合一 SSID部分设备只认 2.4G 隐藏 BSSID。我们现场改单独 2.4G _guest专给摄像机成功率明显上去。第三层配网后 — 轮询上线 绑定// scripts/02-wait-online-and-bind.jsimportdotenv/config;import{platformCall,adminToken}from../lib/platform-call.js;constdeviceIdprocess.env.TARGET_DEVICE_ID;constdeviceCodeprocess.env.DEVICE_CODE;// 8 位安全码或设备密码consttokenawaitadminToken();asyncfunctionwaitOnline(maxTry30,intervalMs2000){for(leti0;imaxTry;i){constinfoawaitplatformCall(unBindDeviceInfo,{token,deviceId});if(info.statusonline)returninfo;if(info.statusupgrading)thrownewError(设备升级中稍后再绑);awaitnewPromise((r)setTimeout(r,intervalMs));}thrownewError(超时设备未上线检查 Wi-Fi/密码/频段);}awaitwaitOnline();awaitplatformCall(bindDevice,{token,deviceId,code:deviceCode});console.log(bindDevice OK);code对照绑定失败第二大坑情况code传什么未改密码标签有 8 位安全码8 位安全码已改设备密码设备密码无 8 位安全码且未改密空字符串code与加密字段encryptCode同时传时以code为准。踩坑 4配网明明成功bindDevice报验证码错误——实施把路由器 Wi-Fi 密码填进了code字段。第四层验收 — 分页列表 信号// scripts/03-verify-asset.jsimportdotenv/config;import{platformCall,adminToken}from../lib/platform-call.js;constdeviceIdprocess.env.TARGET_DEVICE_ID;consttokenawaitadminToken();constpageawaitplatformCall(listDeviceDetailsByPage,{token,pageSize:50,page:1,source:bindAndShare,});constdevpage.deviceList?.find((d)d.deviceIddeviceId);if(!dev||dev.deviceStatus!online){thrownewError(资产池未验收设备不在线或不在本开发者账号);}console.log(验收通过,dev.deviceName,dev.deviceStatus);try{constwifiawaitplatformCall(currentDeviceWifi,{token,deviceId});console.log(当前 Wi-Fi,wifi.ssid,信号,wifi.intensity,/5);if(Number(wifi.intensity)2){console.warn(信号偏弱后续预览可能卡顿建议换 AP 或 wifiAround 选热点);}}catch{console.log(跳过 Wi-Fi 查询可能为有线设备);}配网成功 vs 接入成功✗ App 能预览但 listDeviceDetailsByPage 无此序列号 → 绑在私人账号非开发者主账号 ✓ 分页接口 deviceStatusonline → 才算项目接入完成第五层已绑定设备换 Wi-Fi售后场景设备已进资产池门店换路由器后离线——用周边 Wi-Fi 查询 切换热点切换接口耗时长文档建议超时≥75s// scripts/04-switch-wifi.jsimportdotenv/config;import{platformCall,adminToken}from../lib/platform-call.js;constdeviceIdprocess.env.TARGET_DEVICE_ID;consttokenawaitadminToken();constaroundawaitplatformCall(wifiAround,{token,deviceId});console.log(周边热点,around.wLan?.map((w)({ssid:w.ssid,intensity:w.intensity,linkStatus:w.linkStatus,})));consttargetaround.wLan?.find((w)w.ssidprocess.env.NEW_SSID);if(!target)thrownewError(目标 SSID 不在周边列表中);// 该接口耗时长fetch 建议 signal/timeout ≥ 75sawaitplatformCall(controlDeviceWifi,{token,deviceId,ssid:target.ssid,bssid:target.bssid,linkEnable:true,password:process.env.NEW_WIFI_PASSWORD,});console.log(切换指令已下发等待 online 后验收);踩坑 5未先wifiAround直接controlDeviceWifi平台返回参数错误——BSSID 必须从周边列表取。现场 Checklist可打印□ unBindDeviceInfosupporttruebindStatusunbind □ wifiTransferMode 与路由器频段一致2.4G 机型禁 5G-only □ 配网模式与 wifiConfigMode 匹配 □ Android 定位 / Wi-Fi 权限已开 □ 轮询 statusonline 后再 bindDevice □ code 用安全码/设备密码非 Wi-Fi 密码 □ listDeviceDetailsByPage 验收 online □ 可选currentDeviceWifi intensity ≥ 3四、进阶边界与生产话题建议OpenAPI 边界配网广播在 SDKHTTP 管查、绑、换网批量门店统一 2.4G SSID 规范实施 App 内置 preflight 脚本安全appSecret仅服务端encryptCode绑定接口可选超时controlDeviceWifi长耗时前端勿 30s 断请求旧接口列表用分页查详情勿抄文档里已标注停维护的旧协议有线路径LAN模式设备跳过无线步骤插线上线即绑排错速查现象高概率原因动作一直「搜索设备」2.4G/5G 搞错查 wifiTransferModeSmartConfig 无反应缺定位权限Android 权限online 后 bind 失败code 填错安全码 vs 密码后台查不到设备私人账号绑定开发者主账号重绑换网后离线未 controlDeviceWifiwifiAround → 切换五、收尾配网失败很少是「摄像机坏了」更多是模式、频段、权限、绑定码四件事里有一件没对齐。我们把现场流程收成unBindDeviceInfo能力 → SDK 配网SmartConfig / SoftAP / 声波 → 轮询 online → bindDevice正确 code → listDeviceDetailsByPage 验收脚本化 preflight 之后那个连锁项目配网失败率从大约40% 降到 8%——剩下的多半是现场路由器策略MAC 过滤、访客网络隔离就需要网络同事协同了。如果你也在做云 IPC 批量实施建议把01-preflight.js嵌进实施 App扫码后先出能力报告再让用户选配网方式比反复试错省太多时间。具体接口名与字段以你所对接平台的Wi-Fi 配置 / 设备接入文档为准不同区域网关域名务必按文档填写填错区域的表现和「配网失败」很像。你在现场见过最离谱的配网乌龙是什么欢迎评论区交流。说明本文为个人项目实践笔记接口名称与字段以所对接平台的当前开发者文档为准。