这是连载第三篇:这一次,我们从零开始,把微信小程序开发、测试和发布流程完整走一遍。对嵌入式开发来说,能把设备控制入口从浏览器切到小程序,体验确实提升不少。
ESP8266 到此为止,暂时不再继续折腾了。
前情提要
前两篇里,这块吃灰的 NodeMCU(ESP8266、4MB Flash)已经具备这些能力:
- 自己开热点配网
- 连接路由器
- 通过网页控制 LED
- 控制 4 路继电器
- OTA 上传
.mpy
- 开机通过 UDP 广播自己的 IP
但入口一直是浏览器。手机上的操作流程大致是:
打开浏览器 → 输入 192.168.1.142 → 记住这个地址 → 下次路由器重新分配 IP,再重复一遍。
所以这次做了一个微信小程序:打开后,可以直接在局域网中搜索模块,点进去就能控制。
功能本身并不复杂,真正花时间的是两个“你以为不行、实际上可以”的地方:
后一个问题把我卡了两轮,原因放在后面的“发布翻车”一节说明。
为什么可以零后端
开始之前,我以为需要先买服务器、备案,再配置 HTTPS 域名。实际并不需要。
微信对小程序联网的限制是“只能访问备案过的 HTTPS 域名”,但局域网 IP 是例外:
从基础库 2.4.0 开始,网络接口允许与局域网 IP 通信,但要注意不允许与本机 IP 通信。
换成更直白的说法,下面这种请求可以直接发送:
http://192.168.1.142/api/relay?ch=1&state=on
它不需要配置安全域名,也不要求 HTTPS。条件只有两个:
- 手机和设备处在同一个网段。
- 不要访问手机自己的 IP。
于是,整个方案不需要后端、不需要备案,也没有公网流量。代价是只能在局域网内使用,离开家里或办公室后就无法控制。对于内网设备调试,这个限制刚好可以接受。
设备发现同样走 UDP:
| 能力 |
最低基础库 |
用途 |
| 访问局域网 IP |
2.4.0 |
所有 /api/* 请求 |
wx.createUDPSocket |
2.7.0 |
广播搜索设备 |
setBroadcast: true |
2.9.0 |
真正发出广播包 |
真机上有一个需要注意的现象:收不到 255.255.255.255 的广播包。
不过这里的设计是只发送广播,接收设备的单播应答,因此不会受到这个问题影响。关键点是从设计上绕开了广播接收。
三个页面,各有各的容易写错
| 页面 |
职责 |
设计 |
pages/index |
搜索 |
广播 3 秒收集应答,搜不到时可以手动输入 IP |
pages/device |
控制 |
LED、4 路继电器、WiFi 信号、内存和运行时长,4 秒轮询 |
pages/setup |
配网 |
连接热点、扫描 WiFi、填写密码、保存并重启 |
搜索页:状态机比 if-else 好用
搜索页有 5 个状态:
idle / scanning / empty / error / list
全部放在 data.state 中,WXML 只根据状态显示不同内容。
这样,“搜不到设备”和“搜索出错”就能分别给出提示:
empty:没有搜到设备。确认手机连接的是 2.4G WiFi,并且和板子处在同一个路由器下。
error:当前微信版本不支持 UDP,请手动输入 IP。
这两句看起来只是提示文案,实际上会直接影响用户是否继续追问“为什么搜不到”。
控制页:以设备返回状态为准
继电器使用 switch 组件。通过 bindchange 获取用户想设置的值后,立即发送请求,再回读一次设备状态:
onRelayChange: function (e) {
const ch = e.currentTarget.dataset.ch
const on = e.detail.value
const that = this
net.api.setRelay(
this.data.ip,
ch,
on ? 'on' : 'off'
).then(function () {
that.refresh(true) // 回读,不信本地
}).catch(function () {
wx.showToast({
title: '操作失败',
icon: 'none'
})
that.refresh(true) // 失败也要回读,把 UI 拉回真实状态
})
}
为什么不直接用 setData 修改本地状态?
因为设备可能拒绝请求、可能已经离线,也可能被其他客户端修改。UI 显示状态和继电器实际吸合状态不一致,是这类控制工具最不能接受的问题。用户可能以为灯已经关闭,实际上继电器仍然通电。
轮询定时器要在三个地方清理
小程序页面不像普通浏览器页面,调用 navigateTo 返回时页面不会销毁,只会触发 onHide。因此定时器需要在三个生命周期中处理:
onShow: function () {
this.startPoll()
},
onHide: function () {
this.stopPoll()
},
onUnload: function () {
this.stopPoll()
}
如果漏掉 onHide,就可能出现这样的情况:
控制页 → 配网页 → 配网页中仍然每 4 秒向已经变更 IP 的设备发送请求,日志里充满超时。
startPoll 的第一行也应该先执行 stopPoll(),避免重复进入页面后叠加出多个定时器。
配网页:给扫描接口更长超时时间
板子在 AP 模式下固定使用 192.168.4.1。扫描 WiFi 需要遍历信道,通常比普通接口慢,因此单独设置 15 秒超时,其他接口使用 8 秒:
apScan: function () {
return request(AP_IP, '/api/scan', {
timeout: 15000
})
}
手机连接 nodemcu-setup 热点后,系统可能提示“此网络无互联网连接”。很多人会下意识点击“取消”,导致连接断开。
所以配网页的第一条提示应该明确告诉用户:
请选择“保持连接”。
WXML 不是 HTML
WXML 的表达式只支持有限语法。如果按照 Vue 的习惯直接写,很容易遇到一连串问题。
| 写法 |
能否使用 |
应对方式 |
{{ a.b?.c }} |
不支持 |
{{ a.b && a.b.c }} |
{{ count ?? 0 }} |
不支持 |
{{ count || 0 }} |
{{ list.map(x => x.id) }} |
不支持 |
先在 JS 中计算,再通过 setData 传入 |
{{ formatTime(t) }} |
不支持 |
在 JS 中完成格式化 |
<div>、<span> |
不支持 |
使用 view、text |
{{ list.length ? '有' : '无' }} |
支持 |
三元表达式可以使用 |
wx:for + wx:key |
支持 |
建议都提供 wx:key |
函数调用不支持这一点尤其容易忽略。WXML 中写:
{{ fmt(x) }}
通常不会直接提示“函数不存在”,而是静默渲染为空。页面看起来没有崩溃,但数据就是不显示,排查起来很费时间。
因此我写了一个静态校验脚本 tools/validate.js,共检查 52 项,分为 6 组:
1) JSON 严格性 —— app.json 和各页 .json 必须是严格 JSON
不能有注释,也不能有尾逗号
2) JS 语法 —— 每个 .js 文件都能被 new Function 解析
3) 页面完整性 —— app.json 中的页面是否都有
.js / .json / .wxml / .wxss 四个文件
4) WXML 规范 —— 禁用语法扫描,以及标签闭合数量配平
5) 事件方法引用 —— WXML 中 bindtap="foo" 的 foo
必须在 Page 中存在
6) 网络层 —— utils/api.js 的导出是否完整
完整运行一次只需要约 200 毫秒,比“上传、等待服务端校验、返回错误”快两个数量级。
其中第 4 组和第 5 组最有价值,因为这两类错误在小程序里经常表现为运行时静默失败。不做校验,就只能靠肉眼排查。
这套思路也是前面“三层测试”的延伸:先在静态层面把能检查的问题全部拦住,不要让机器可以发现的问题浪费人工时间。
UDP 在小程序里的实现
核心流程只有四步:
createUDPSocket → bind → onMessage → send({ setBroadcast: true })
但具体实现中有几个容易踩坑的细节。
坑一:收到的是 ArrayBuffer,不能直接使用 TextDecoder
小程序中没有 TextDecoder,res.message 返回的是 ArrayBuffer。板子返回的是 UTF-8 编码的 JSON,因此需要自行解码:
function decodeMessage(message) {
let text = ''
if (typeof message === 'string') {
text = message
} else if (message instanceof ArrayBuffer) {
const bytes = new Uint8Array(message)
let i = 0
while (i < bytes.length) {
const b = bytes[i]
if (b < 0x80) {
// ASCII
text += String.fromCharCode(b)
i += 1
} else if (
b >= 0xc0 &&
b < 0xe0 &&
i + 1 < bytes.length
) {
// 2 字节
text += String.fromCharCode(
((b & 0x1f) << 6) |
(bytes[i + 1] & 0x3f)
)
i += 2
} else if (
b >= 0xe0 &&
i + 2 < bytes.length
) {
// 3 字节,中文
text += String.fromCharCode(
((b & 0x0f) << 12) |
((bytes[i + 1] & 0x3f) << 6) |
(bytes[i + 2] & 0x3f)
)
i += 3
} else {
i += 1
}
}
}
try {
return JSON.parse(text)
} catch (e) {
return null
}
}
如果省略中文对应的 3 字节分支,板子返回的 JSON 里只要 host 字段包含中文,就会出现乱码。
坑二:广播可能丢,补发一次
UDP 广播本身不保证送达,路由器忙时可能丢包。因此隔 800 毫秒再发一次:
const targets = ['255.255.255.255']
const prev = lastIp()
if (prev) {
targets.push(prev) // 上次连接过的 IP,单播兜底
}
targets.forEach(sendTo)
setTimeout(function () {
targets.forEach(sendTo)
}, 800)
lastIp 对应的单播地址是兜底方案。有些路由器会拦截广播,但单播仍然可以正常工作。
原则很简单:广播不可靠时,就用最笨的单播。
坑三:socket 不关闭,下一次 bind 会失败
在 finish() 中统一执行 socket.close(),同时使用 finished 标志防止重复进入。因为超时、错误和异常都可能调用结束逻辑:
let finished = false
function finish(error) {
if (finished) {
return
}
finished = true
try {
socket.close()
} catch (e) {}
// ...
}
setTimeout(function () {
finish('')
}, 3000) // 3 秒到点,不管收到几个都结束
3 秒是一个折中值。设备通常几十毫秒就能应答,但部分路由器可能慢一些。等 3 秒用户还能接受,等 5 秒就容易让人怀疑页面卡死。
发布翻车:npm install failed (code=null, signal=SIGTERM)
这是整个过程里最值得记录的一部分。
点击“发布体验版”后,出现了下面的错误:
小程序发布校验未完成。
npm install failed (code=null, signal=SIGTERM)
npm warn deprecated debuglog@1.0.1: Package no longer supported...
npm warn deprecated readdir-scoped-modules@1.1.0: ...
npm warn deprecated inflight@1.0.6: ...
...(还有四十多行)
先做一个减法:
四十多行 deprecated 都是 npm 安装依赖时打印的弃用提醒,和这次失败没有直接关系。真正有用的是:
npm install failed
以及:
code=null, signal=SIGTERM
code=null 表示什么
npm 出错时,通常会带退出码,例如:
code=1
code=ENOENT
这里是 code=null,同时出现 signal=SIGTERM。
code=null 加上 signal,说明进程不是自行报错退出,而是被信号终止。SIGTERM 可以理解为“请停止”,常见原因是进程超过了约定的超时时间。
因此问题不是依赖包坏了,也不一定是网络断开,而是:
安装太慢,进程被超时终止。
为什么没有 package.json,仍然会安装依赖
这个小程序是纯原生手写的,没有 package.json,也没有 node_modules。按道理,“npm 构建”这一步应该什么都不做。
通过发布客户端安装包中的 app.asar 反查错误字符串,可以看到大致流程:
input
→ locateProject
→ assemble(复制到临时目录)
→ [npm]
→ filter
→ transpile
→ validate
→ zip
→ submit
npm 步骤会先探测是否存在构建目标,如果没有,就直接返回。
真正的问题在于,npm、filter、transpile 和 validate 都要使用微信官方编译工具链,而这些工具会在首次发布时现场安装:
| 组件 |
版本 |
用途 |
miniprogram-ci |
2.1.31 |
打包、依赖分析、packOptionsHelper |
miniprogram-compiler |
0.2.3 |
提供 wcc.exe、wcsc.exe,编译 WXML 和 WXML / WXSS |
@babel/core + preset-env |
7.27.4 / 7.27.2 |
JavaScript 转译 |
miniprogram-ci 安装完成后,node_modules 中大约有 695 个条目。相关逻辑大致如下:
// 伪代码,去掉压缩后的变量名
await writeFile(
join(dir, 'package.json'),
JSON.stringify({
private: true,
dependencies: {
'miniprogram-ci': '2.1.31'
}
})
)
await installDependencies(dir, env) // npm install
而 npm install 的超时时间是固定的:
spawn('npm', args, {
cwd,
env,
timeout: 300000
}) // 300000ms = 5 分钟
5 分钟内安装 695 个包,在国内网络环境下跑不完并不罕见。超时后进程收到 SIGTERM,最终就看到:
code=null, signal=SIGTERM
为什么配置了镜像仍然很慢
系统 npm 明明配置了国内镜像:
$ npm config get registry
https://registry.npmmirror.com
但发布流程使用的是隔离环境,它修改了 npm 配置文件和缓存目录:
if (installPath) {
env.NPM_CONFIG_USERCONFIG =
join(installPath, '.npm-config', '.npmrc')
env.NPM_CONFIG_GLOBALCONFIG =
join(installPath, '.npm-config', '.npmrc')
env.NPM_CONFIG_CACHE =
join(installPath, '.npm-cache')
}
一旦设置了 NPM_CONFIG_USERCONFIG,系统中的 ~/.npmrc 就不会再被读取。
而发布流程指定的 .npmrc 原本并不存在,于是 npm 回退到默认源:
registry.npmjs.org
从国内网络环境向默认源拉取 695 个包,5 分钟通常不够。
一句话总结:
镜像配置在 A 处,发布流程使用的是 B 处。
这也是“我明明配置了国内镜像,为什么安装还是慢”很难自行定位的原因。
修复方法:从现场安装改成提前准备
发布流程通过工具目录中的 .ready 文件判断工具是否已经准备好。文件内容是版本号,并且会进行精确匹配:
const r = await readFile(
join(dir, '.ready'),
'utf8'
).catch(() => undefined)
if (r !== '2.1.31') {
// 版本不相等就重新安装
await writeFile(
join(dir, 'package.json'),
'...'
)
await install(dir)
}
处理步骤如下:
- 使用镜像,手动安装完整的
miniprogram-ci@2.1.31。安装完成后,node_modules 应包含约 695 个条目,并且 require('miniprogram-ci') 可以正常加载。
- 手动安装完整的
miniprogram-compiler@0.2.3,确认 wcc.exe 和 wcsc.exe 都存在。
- 在三个工具目录中分别写入
.ready 文件,内容为对应版本号。
- 在发布流程指定的位置补上
.npmrc,内容为:
registry=https://registry.npmmirror.com
.ready 文件有一个容易忽略的细节:内容必须精确等于版本字符串,不能带换行。
因为代码使用的是字符串全等比较:
r !== '2.1.31'
如果编辑器保存文件时自动补上 \n,比较就会失败,工具仍然会被认为没有准备好。
可以这样验证文件内容:
$ od -c .ready
0000000 2 . 1 . 3 1
0000006
这里应该只有 6 个字节,不包含换行符。
改完后,按照发布流程的判断逻辑模拟一次,确认会跳过安装:
1) miniprogram-ci .ready = "2.1.31" -> 跳过安装: true
packOptionsHelper: object | packNpmManually: function
2) wcc/wcsc .ready = "0.2.3" -> 跳过安装: true
wcc.exe: true | wcsc.exe: true
3) babel .ready = "7.27.4_7.27.2"
@babel/core 可加载: true
从错误日志中找真正有价值的信息
报错文本中的信息价值并不相同:
| 类型 |
例子 |
价值 |
| 结论 |
npm install failed |
低,只说明失败了 |
| 噪音 |
多行 deprecated |
几乎没有,反而可能误导排查 |
| 指纹 |
code=null, signal=SIGTERM |
高,直接指向进程被终止 |
正确的阅读顺序应该是:
先看退出码和信号,再看日志正文。
我第一眼盯着那几十行警告,差点去查 gulp-util 为什么不再维护。先识别退出信号,能省掉很多无效排查。
把发布校验搬到本地
发布流程中的 validate 主要做两件事:
- 使用
wcc.exe 编译所有 WXML。
- 使用
wcsc.exe 编译所有 WXSS,并进行依赖分析。
既然工具已经在本机,就没有必要每次上传后再等待服务端校验。
按照它的传参方式,将参数写入 args.txt,再通过 --config-path 指定:
-d
-gn
$gwx
pages/index/index.wxml
pages/device/device.wxml
pages/setup/setup.wxml
运行 WXML 编译:
$ wcc.exe --config-path args.txt
exit=0
WXSS 使用 -db -pc 4,并传入 4 个样式文件:
app.wxss
pages/index/index.wxss
pages/device/device.wxss
pages/setup/setup.wxss
同样确认:
exit=0
加上前面的 52 项静态校验,本地已经可以拦截发布校验中的绝大部分问题。上传前先跑这几步,就不必反复经历“发布一次、修改一次”。
项目结构
目前项目结构如下:
nodemcu-miniapp/
├── app.js / app.json / app.wxss 入口与全局样式
├── pages/index 搜索:UDP 广播、手动 IP、历史设备
├── pages/device 控制:LED、4 路继电器、状态、4 秒轮询
├── pages/setup 配网:连接热点、扫描 WiFi、保存
├── utils/api.js 网络层:UDP 发现、HTTP、本地存储
└── tools/validate.js 静态校验 52 项
协议和固件侧已经对齐,增加小程序没有修改固件代码。
| 用途 |
请求 |
| 发现 |
UDP 广播 NODEMCU? 到 8266 端口,模块单播返回 JSON |
| 状态 |
GET /api/status |
| LED |
GET /api/led?state=on\|off\|toggle |
| 继电器 |
GET /api/relay?ch=N&state=on\|off\|toggle,其中 ch=all 表示全部通道 |
| 重新配网 |
GET /api/forget,清除配置并重启进入 AP 模式 |
| 扫描 WiFi |
GET http://192.168.4.1/api/scan |
| 保存 WiFi |
POST http://192.168.4.1/api/save,请求体为 ssid=..&pwd=.. |
这也是前两篇接口设计的回报:固件把能力封装成 HTTP 后,客户端换成什么形式,都只是更换调用方式。网页、小程序以及后续可能接入的 MQTT,都可以复用同一套接口。
实际界面



还没做的事
- 体验版发布刚修好工具链,还没有走完最后一步。第五节的修复已经在本机验证,包括工具链就绪,以及
wcc、wcsc 编译通过,但真正的上传发布还需要再点击一次。
- MQTT 还没有接入。本来打算在这一篇中一起完成,但评估后发现内存和配置页面还需要进一步调整,板上只剩约 15KB,计划放到下一篇。
写完之后,一个比较重要的感受是:能明确说明哪些已经验证、哪些还没有验证,比直接说“全部跑通”更有用。读者照着做时,最需要知道的是每一步应该看到什么结果。
本文涉及的 7 个坑
| # |
现象 |
真正原因 |
解法 |
| 1 |
发布时报 npm install failed (code=null, signal=SIGTERM) |
首次发布现场安装 695 个包,5 分钟超时后被 SIGTERM 终止 |
提前安装工具链,并写入 .ready |
| 2 |
已配置国内镜像,安装仍然很慢 |
发布流程覆盖了 NPM_CONFIG_USERCONFIG,读取不到 ~/.npmrc |
在指定路径补充 .npmrc |
| 3 |
.ready 写对了却不生效 |
编辑器自动添加换行,字符串全等比较失败 |
使用 printf 写入,并用 od -c 确认只有 6 个字节 |
| 4 |
WXML 中 {{ fmt(x) }} 不报错但不显示 |
WXML 表达式不支持函数调用,静默渲染为空 |
在 JS 中格式化,再通过 setData 传递结果 |
| 5 |
UDP 收到的 JSON 中文乱码 |
小程序没有 TextDecoder,message 是 ArrayBuffer |
手写 UTF-8 解码,处理 3 字节分支 |
| 6 |
第二次搜索时 bind() 报错 |
上一次 socket 没有关闭 |
使用 finish() 统一 close,并用 finished 防止重入 |
| 7 |
从配网页返回控制页后日志充满超时 |
onHide 没有清除轮询定时器 |
在 onShow、onHide、onUnload 三处处理 |
前两篇涉及的复位时序、双波特率、bytes 没有 partition、send() 部分发送、_mpy 版本号位于低字节、广播只从一张网卡发出,以及内存被模块占用等问题,这里不再重复。
本文中的报错、日志和退出码均来自真实环境:
Windows 10.0.26300
Node 22.22.2
WorkBuddy 小程序发布链路
ESP8266EX
MicroPython v1.29.0
来源