MicroWebSrv完全指南：轻量级MicroPython Web服务器如何3步实现嵌入式Web应用

MicroWebSrv完全指南：轻量级MicroPython Web服务器如何3步实现嵌入式Web应用

【免费下载链接】MicroWebSrvA micro HTTP Web server that supports WebSockets, html/python language templating and routing handlers, for MicroPython (used on Pycom modules & ESP32)项目地址: https://gitcode.com/gh_mirrors/mi/MicroWebSrv

MicroWebSrv 是一款专为 MicroPython 设计的轻量级嵌入式 Web 服务器框架，仅凭 3 个 Python 文件，就能在 ESP32、Pycom 等开发板上跑起完整的 Web 应用。它同时支持 HTTP 路由处理、WebSocket 实时双向通信和 .pyhtml 模板渲染，是目前搭建 MicroPython Web 服务器最省心、最轻量的方案之一。本文将带你从零上手，用 3 个步骤完成第一个嵌入式 Web 应用。

MicroWebSrv是什么？轻量级MicroPython Web服务器核心能力速览

MicroWebSrv 由法国开发者 Jean-Christophe Bos 开源维护，专为资源有限的 MicroPython 设备设计。它把"服务器"这件听起来很重的事，压缩到了极致：

• 极轻量：整个框架只有 3 个文件，无需任何第三方依赖；
• 全协议支持：HTTP 的 GET/POST 等请求、WebSocket 实时通信、文件在线分发一应俱全；
• 模板引擎：内置 .pyhtml 模板，HTML 中直接嵌入 MicroPython 代码，动态渲染页面毫不费力；
• 路由系统：支持固定路由与变量路由（如/edit/<id>），还能一键做成 REST API；
• 平台友好：官方支持 ESP32、Pycom 模块以及 Pyboard D 系列开发板。

3个文件，撑起一个完整的Web服务器

项目的核心结构异常简洁，这正是它"轻量级"的底气所在：

• microWebSrv.py—— 主服务器模块，负责 HTTP 服务、路由分发与文件服务；
• microWebSocket.py—— 可选模块，加上它即可启用 WebSocket 实时通信；
• microWebTemplate.py—— 可选模块，用于渲染 .pyhtml 动态模板页面。

把这三个文件放进开发板的 flash 文件系统，你的设备就具备了成为一台微型 Web 服务器的全部条件。

3步实现嵌入式Web应用：最快搭建MicroPython Web服务器的方法

下面这份"三步走"教程，全程只需几行代码，非常适合新手照做。

第1步：获取MicroWebSrv源码并部署到开发板

先在电脑上克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/mi/MicroWebSrv

克隆完成后，你会看到microWebSrv.py、microWebSocket.py、microWebTemplate.py以及一个www/示例站点目录。把这三个 .py 文件连同www/目录一起上传到开发板的 flash 中即可。项目中自带的main.py就是一个开箱即用的演示程序，直接参考它能省去不少摸索时间。

第2步：用几行代码启动你的第一个MicroPython Web服务器

在开发板上新建一个main.py（或直接使用仓库自带示例），写入以下内容：

from microWebSrv import MicroWebSrv mws = MicroWebSrv() # 默认端口80，网页目录 /flash/www mws.Start(threaded=True) # 以独立线程启动服务器

就这么简单！构造函数支持自定义端口、绑定 IP 和网页目录，例如MicroWebSrv(webPath='www/')即可指定站点文件所在路径。Start(threaded=True)让服务器在后台线程运行，主程序可以继续执行其他逻辑，比如读取传感器数据。

第3步：启动服务器并用浏览器验证效果

把程序部署到开发板并重启，然后在同一局域网内的电脑或手机上访问开发板的 IP 地址（如http://192.168.1.100）。如果一切正常，你会看到www/目录下index.html渲染出的测试页面——这意味着你的嵌入式 Web 应用已经跑起来了。

更妙的是，默认首页会按index.pyhtml、index.html、index.htm、default.pyhtml等顺序自动查找，你可以灵活决定用静态页面还是动态模板作为入口。

进阶玩法：路由、WebSocket与模板渲染的实用技巧

跑通基础版之后，下面的进阶功能能让你的嵌入式 Web 应用真正"高级"起来。

用路由处理GET/POST请求，快速搭建设备配置页面

通过@MicroWebSrv.route()装饰器，一行代码即可注册接口。项目main.py中就有现成范例：

@MicroWebSrv.route('/test', 'POST') def _httpHandlerTestPost(httpClient, httpResponse): formData = httpClient.ReadRequestPostedFormData() ...

配合httpClient.ReadRequestPostedFormData()读取表单、httpResponse.WriteResponseJSONOk()返回 JSON，你就能轻松实现设备参数在线配置，甚至做出一个完整的嵌入式 REST API。

变量路由：让URL携带动态参数

使用尖括号即可定义变量路由，例如/edit/<index>/abc/<foo>。请求http://设备IP/edit/123/abc/bar时，处理器会收到routeArgs['index']='123'、routeArgs['foo']='bar'，非常适合实现"按 ID 查看或编辑某个数据项"这类场景。

WebSocket实时通信：打造毫秒级双向数据传输

WebSocket 是嵌入式 Web 应用的一大亮点。启用方法很简单：设置AcceptWebSocketCallback回调，再通过ws.SendText()推送数据、ws.RecvTextCallback接收消息即可。项目中的www/wstest.html就是一个完整的 WebSocket 测试页面，配合microWebSocket.py使用，非常适合做实时传感器数据展示、远程控制等应用。

.pyhtml模板：在HTML中直接写MicroPython代码

模板模块支持{{ py }}、{{ if }}、{{ for }}、{{ include }}等指令，你可以在 HTML 里循环输出数据、按条件渲染区块，甚至引用设备上的变量。仓库中的www/test.pyhtml展示了完整的语法用法，静态页面交给模板渲染后，交互体验会大幅提升。

这些场景最适合使用MicroWebSrv

• 智能家居网关：设备本地提供配置页面，无需依赖云端；
• 传感器数据看板：WebSocket 实时推送温湿度、电量等数据到浏览器；
• 设备文件导出：httpResponse.WriteResponseFile()可在线分发日志或 PDF 报告（仓库www/test.pdf就是现成示例）；
• 强制门户（Captive Portal）：调用SetNotFoundPageUrl()即可拦截未匹配请求并跳转，配合认证页面实现 Wi-Fi 配网。

常见问题与排查建议

• 页面打不开？先确认开发板与电脑在同一网段，再用串口查看启动日志是否报错；
• WebSocket 不生效？检查是否已上传microWebSocket.py，文件缺失时该功能会被自动禁用；
• 内存告急？可通过mws.MaxWebSocketRecvLen调低 WebSocket 单次接收上限（默认 1024 字节），为设备腾出更多内存。

结语

MicroWebSrv 用 3 个文件把"在嵌入式设备上搭建 Web 应用"这件事变得足够简单：3 步上手、几行代码、开箱即用。无论你是刚接触 ESP32 的新手，还是想快速给产品加上 Web 配置界面的开发者，它都是值得一试的 MicroPython Web 服务器利器。动手部署一次，你会立刻感受到轻量级嵌入式 Web 开发的乐趣。

【免费下载链接】MicroWebSrvA micro HTTP Web server that supports WebSockets, html/python language templating and routing handlers, for MicroPython (used on Pycom modules & ESP32)项目地址: https://gitcode.com/gh_mirrors/mi/MicroWebSrv