找回密码
立即注册
搜索
发回帖 发新帖

5296

积分

0

好友

678

主题
发表于 4 小时前 | 查看: 14| 回复: 0

这是连载第三篇:这一次,我们从零开始,把微信小程序开发、测试和发布流程完整走一遍。对嵌入式开发来说,能把设备控制入口从浏览器切到小程序,体验确实提升不少。

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。条件只有两个:

  1. 手机和设备处在同一个网段。
  2. 不要访问手机自己的 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)
}

处理步骤如下:

  1. 使用镜像,手动安装完整的 miniprogram-ci@2.1.31。安装完成后,node_modules 应包含约 695 个条目,并且 require('miniprogram-ci') 可以正常加载。
  2. 手动安装完整的 miniprogram-compiler@0.2.3,确认 wcc.exe 和 wcsc.exe 都存在。
  3. 在三个工具目录中分别写入 .ready 文件,内容为对应版本号。
  4. 在发布流程指定的位置补上 .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 主要做两件事:

  1. 使用 wcc.exe 编译所有 WXML。
  2. 使用 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

来源




上一篇:ESP8266 MicroPython 实战:继电器、OTA 升级与 UDP 广播找 IP
下一篇:MCU 加 NPU 还是加缓存?六家厂商的三种方案与选型思路
您需要登录后才可以回帖 登录 | 立即注册

关闭

站长推荐上一条 /1 下一条

手机版|小黑屋|网站地图|云栈社区 ( 苏ICP备2022046150号-2 )

GMT+8, 2026-11-21 11:08 , Processed in 0.113815 second(s), 40 queries , Gzip On.

Powered by Discuz! X3.5

© 2025-2026 云栈社区.

快速回复 返回顶部 返回列表