我电脑里至今躺着一堆串口调试工具SSCOM 在 Windows 上稳minicom 在 Linux 上够用macOS 偶尔还得翻出 screen 现查参数。但每次换电脑、换系统、带团队联调的时候这些本地工具就变成一个很烦人的包袱。直到我系统试了基于 Web Serial API 的开源 Web 串口调试工具——浏览器打开即用Chrome 一开、USB 一插页面里就能看日志、发指令、画波形。这篇就聊聊这类开源的浏览器串口调试方案的底层原理、功能拆解和实战踩坑适合被传统串口助手折腾过的嵌入式开发、硬件调试和 IoT 学习者参考。1. 传统串口助手的三大痛点以及浏览器方案为什么能补上1.1 我桌上为何堆着三四个串口工具干嵌入式的人都有过这种经历项目一开始用 Windows 下的 SSCOM连上开发板收日志功能没问题但换到 Linux 之后就得改用 minicom还要先背一遍minicom -D /dev/ttyUSB0 -b 115200的参数。macOS 上逼急了直接screen /dev/cu.usbserial-xxx 115200但 screen 的串口模式没有滚动缓冲区日志一刷就全没影。更麻烦的是设备多了之后某个串口号被占用你要在设备管理器里一个个认或者用 udevadm 去翻设备节点。这些工具单一场景下都挺好但放在一起就是三座大山安装和依赖隔离在各个操作系统里换环境成本极高。数据不好带走。SSCOM 保存的日志格式、编码、时间戳跟你自己用 minicom 记下来的完全不是一套东西。波形和格式解析基本靠个人。PID 调试时我想直观看到曲线变化传统助手很难直接做到。我后来转向开源的 Web 串口调试工具核心原因不是省一次安装而是它把整个调试环境统一到了浏览器这一个载体里。项目组里任何人打开同一个 URL看到的是同一套收发界面、同一套解析逻辑联调和复现问题时的沟通成本大幅下降。1.2 Web 方案解决的是工程协作问题不只是省一次安装这类工具一般基于 Web Serial API整个应用就是一堆静态文件HTML、CSS、JavaScript。你可以把它扔到内网随便一台静态服务器上团队所有人用 Chrome 或 Edge 打开同一个地址点一下连接按钮就能对着同一款开发板调试。没有安装包不需要配 PATH不需要管 Windows 和 Linux 下的执行文件差异。从前期的原型联调到现场故障排查效率提升主要来自三点环境一致性。你在 chrome 里看到的收发界面同事在 Edge 里看到的一模一样连波特率选项和 Hex 切换逻辑都完全一致。可复用配置。很多 Web 串口工具支持把工作区里的波特率、解析模板、图表字段导出成 JSON文档里附一份拿到任何机器上导入即可。可以嵌进自己的 Web 工程。比如在内部测试平台上挂一个串口调试组件和 CI/CD、设备管理面板联动这是传统桌面助手做不到的。但这里有一个必须说清楚的现实浏览器打开即用指的是应用本身不用安装不代表串口驱动可以省掉。你的 USB 转串口芯片CH340、CP2102、FTDI 这些在系统层面依然要有驱动支持Linux 下还得有 dialout 组权限。浏览器只是把你调驱动的过程藏到了后台底层依赖并没有消失。2. Web Serial API 原理拆解浏览器访问串口的权限链路2.1 硬件层从 USB 到 COM/TTY 的漫长旅程要理解浏览器为什么能碰串口得先搞清楚串口设备在系统里到底是怎么存在的。以最常见的 USB 转串口方案为例开发板上的 UART 引脚经过 CH340 或 CP2102 芯片转换成 USB 信号插入电脑后操作系统通过 USB CDC ACM 协议识别出这是一个通信设备然后加载对应驱动把它映射成一个虚拟串口节点。Windows 里你看到的是 COM3、COM5 这种编号Linux 里是/dev/ttyUSB0或/dev/ttyACM0macOS 里是/dev/cu.usbserial-xxx。所以串口在操作系统眼里就是一个设备文件或者一个驱动抽象的 I/O 通道。浏览器没有能力自己写一个 USB 驱动它做的是在浏览器进程里调用操作系统提供的串口访问接口。Chromium 的串口服务在后台完成对这个设备节点的 open、read、write、设置波特率等底层操作前端 JavaScript 只通过navigator.serial这几个 API 跟它对话。这也是为什么 Web Serial 支持的平台范围完全取决于浏览器而不是取决于你买的是哪家的开发板。2.2 浏览器做了什么navigator.serial 的权限模型前端侧核心 API 并不多但权限模型很关键navigator.serial.requestPort()弹出系统设备选择框让用户手动选一个串口。这个调用必须发生在用户手势里比如点击按钮的事件回调中否则直接报 SecurityError。navigator.serial.getPorts()获取当前页面已经被授权过的端口列表。同源页面再次访问时可以直接拿到之前选过的设备不需要重新弹窗。port.open({ baudRate, dataBits, stopBits, parity, flowControl })按参数打开串口返回 Promise。port.readable一个 ReadableStream通过getReader()拿到底层数据。port.writable一个 WritableStream通过getWriter()写入数据。port.getSignals()和port.setSignals()读取、设置 DTR、RTS 等控制线状态。一个最小可用的打开流程是这样const port await navigator.serial.requestPort(); await port.open({ baudRate: 115200, dataBits: 8, stopBits: 1, parity: none }); const decoder new TextDecoder(); const reader port.readable.getReader(); while (true) { const { value, done } await reader.read(); if (done) break; // 这里拿到的是 Uint8Array需要自己拼帧 processData(decoder.decode(value)); }权限模型的设计逻辑很清楚浏览器不允许网页在后台静默探测你的串口设备每一次访问都必须让你知道。用户可以在浏览器的站点设置里看到这个页面被授予了哪些串口设备的访问权也可以随时撤销。这种每次都要明确授权的交互对开发者来说是一种麻烦但对安全性来说是必要的毕竟串口协议往往没有加密和鉴权。2.3 支持矩阵Chrome/Edge 能用Safari 别想Web Serial API 目前的浏览器支持情况比较干脆主力的 Chromium 系浏览器都行但 Firefox 和 Safari 至今没有默认开放。浏览器支持情况备注Chrome 89完整支持桌面端稳定可用Android 端在 USB OTG 场景也能用Edge 89完整支持内核同为 Chromium体验与 Chrome 一致Opera 76完整支持Chromium 内核Firefox需手动开启 flag默认关闭生产环境不建议依赖Safari / iOS Safari不支持暂无明确计划所以如果你要给团队部署 Web 串口调试工具直接规定用 Chrome 或 Edge 就行这在实际工程中不是大问题因为嵌入式团队基本人手一个 Chromium 浏览器。真正麻烦的是浏览器版本太旧的现场。我的建议是统一升级到较新的版本因为早期实现里 Web Serial 的 API 细节还有一些小变化老版本很容易踩到getPorts()不返回已授权端口之类的坑。3. 开源项目功能拆解一个浏览器串口助手的完整能力地图3.1 核心收发连接管理、按帧读取、Hex/ASCII 切换这类开源项目的典型界面通常就是顶部连接区 中间收发区 底部状态栏的布局。连接区有端口下拉、波特率选择、打开/关闭按钮收发区可以切换 ASCII 和 Hex 显示。按帧读取是我建议大家一定要有的功能。串口数据是字节流没有帧边界你需要根据场景自己拼。最常见的按行读取是切到\n我做过一个定制版本是按固定字节数分包还有一个是每隔 10ms 把缓冲区的数据作为一帧推给前端图表。核心逻辑不复杂但直接决定了数据能不能被正确解析。function parseLineStream(chunk) { buffer chunk; let index; while ((index buffer.indexOf(\n)) 0) { const line buffer.slice(0, index); buffer buffer.slice(index 1); handleLine(line); } }Hex 模式做 Modbus 调试时尤其有用。很多工业仪表、传感器用的是 Modbus RTU你要发一帧01 03 00 00 00 01 84 0A这样的十六进制指令传统助手能发就不错了但 Web 工具可以在前端直接做 CRC16 计算和校验避免手算出错的窘境。我实际调过一个温控器靠的就是浏览器里直接粘贴 Modbus 指令 自动算 CRC比拿计算器一个个按快太多了。3.2 调试利器从日志回放到 PID 实时曲线PID 调试是这类工具最出彩的地方。以前调 PID要么用串口助手的文本刷屏自己脑补曲线要么导出 CSV 后用 Excel 画图来回折腾半天。我把 STM32 和 ESP32 的 PID 运行参数通过串口按 JSON 格式打出来Web 工具里选好字段曲线实时就出来了。MCU 侧只需要简单输出结构化数据{t:1200,kp:2.1,ki:0.05,kd:0.08,set:300,cur:287} {t:1210,kp:2.1,ki:0.05,kd:0.08,set:300,cur:291}前端拿到后按行解析把cur和set分别映射到两条曲线刷新到 Canvas 或 SVG 图表里。调完 Kp 改成 3.5下一秒曲线就能看到超调量变大、振荡周期变短这种反馈速度是文本日志给不了的。日志导出也顺手做了。浏览器里直接把收发的原始数据用 Blob 包一下生成文件下载不依赖任何后端const blob new Blob([logContent], { type: text/plain;charsetutf-8 }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download serial-log.txt; a.click(); URL.revokeObjectURL(url);3.3 工程化细节依赖少、可自托管、可二次开发我复现这套方案时前端技术栈用的是 Vite TypeScript图表只引入一个轻量库加起来没多少依赖。整个项目就是静态资源构建完扔到 nginx、NAS 或者任何静态文件服务里就能跑不需要数据库不需要后端服务省掉了大量运维负担。因为它是纯前端项目二次开发的成本也很低。你可以把它拆成组件嵌到自己的 Web 工程里也可以直接改源码加功能。我见过有人把它接进公司内部的设备测试系统串口数据直接入库还有人基于它做了产线自动化测试的页面。这种一个静态页面解决一个调试场景的思路非常适合中小团队快速落地。4. 从零上手实测ESP32 日志采集与 PID 波形调试全流程4.1 准备环节浏览器、驱动、权限三件事实操之前先把环境扫一遍缺哪一个都跑不通。第一浏览器版本。Chrome 89 以上或 Edge 89 以上这个基本都能达标。检查方法很简单打开一个 HTTPS 页面或者 localhost 页面在控制台输入navigator.serial能出对象就说明支持。第二串口驱动。我用的 ESP32 开发板板载 CH340Windows 下如果插上没反应先去装 CH340 驱动。Linux 下多数发行版自带 CDC ACM 驱动但当前用户必须有 dialout 组权限否则打开设备会报权限不足sudo usermod -aG dialout $USER改完用户组要重新登录一次生效。插上开发板后用ls /dev/ttyUSB*确认设备节点存在。第三安全上下文。Web Serial 只在安全上下文里可用。最简单的方式是本地起一个服务访问http://localhost:5173或http://127.0.0.1:8080localhost 天然算安全上下文。千万不要用局域网 IP 裸 HTTP 访问会被浏览器判定为不安全上下文后面专门讲这个坑。4.2 连接 ESP32一次完整的设备授权过程准备完成后把 ESP32 通过 USB 线插到电脑打开调试页面点击连接按钮。此时浏览器会弹出系统级设备选择窗口列出当前可用的串口设备。我这边显示的是USB-Enhanced-SERIAL CH340旁边会带设备 VID/PID 信息。选完点连接工具内部会调用port.open()打开串口设置 115200 波特率。连接成功后ESP32 的启动日志会直接刷到收发区。这时候就能验证收发链路了在发送框输入一条指令观察开发板是否响应。ESP32 的自动下载电路依赖 DTR 和 RTS 两个控制信号部分 Web 串口工具会在连接时默认置位这两个信号如果你发现点连接后开发板直接进入下载模式而不是正常运行那大概率是 DTR/RTS 状态没设置对。此时需要手动关掉自动下载相关的信号控制或者检查工具是否支持setSignals()的配置。4.3 波形可视化把串口文本变成实况曲线波特率跑通之后我给 ESP32 刷了一个简单的 PID 温控程序让它每 10ms 输出一次控制量和实际温度。在 Web 工具的解析配置里指定 JSON 解析模板把cur字段和set字段加进曲线视图图表立刻开始滚动。调参过程非常直观我把 Kp 从 2.0 提到 3.0曲线从原本的缓升变成了带明显超调的上升峰值甚至冲过了目标线再把 Ki 调小一点稳态误差慢慢收掉。整个过程没有导出过一次文件所有调参反馈都在同一个页面里闭环实测下来一次 PID 整定的时间比传统方式缩短了大半。提示PID 数据采样周期不要太长建议 10ms 到 50ms 一组。采样太稀疏时曲线会丢失振荡细节你会误以为参数很稳实际上系统已经在振荡了。5. 跨浏览器兼容与踩坑实录五个必须提前知道的问题5.1 坑一没在用户手势里调用 requestPort直接 SecurityError第一次我图省事在页面加载完成时自动调用navigator.serial.requestPort()结果控制台直接抛 SecurityError。原因我之前提过Web Serial 的授权必须由用户手势触发。这个限制无法绕过唯一正确的做法就是把requestPort()放进按钮的点击事件回调里。如果你真的要页面一进来就自动连上次设备可以先在后台调用getPorts()拿已授权端口列表。如果拿到了且只有一个直接尝试open()即可这个过程不需要用户手势因为授权已经存在了。如果列表为空再引导用户点击连接按钮。5.2 坑二HTTP 内网地址被浏览器判定为不安全上下文我在内网服务器上部署了一个调试页面同事通过http://192.168.1.10:8080访问结果点击连接没有任何反应控制台报错提示 API 只能在安全上下文中使用。localhost 没问题但局域网 IP 的纯 HTTP 页面不被信任。解决思路有几个部署到带 HTTPS 的网关后面用 nginx 反代加证书。本地开发时用 Chrome 的启动参数临时把某个内网地址标记为安全来源仅限开发阶段chrome --unsafely-treat-insecure-origin-as-securehttp://192.168.1.10:8080如果只是自己用直接访问 localhost 加端口映射也行但团队成员之间协作时这个方案不现实。我的建议是把调试工具部署在内网 HTTPS 网关下当成标准配置一劳永逸。5.3 坑三串口被其他程序独占浏览器报 Access Denied这是 Windows 上最常见的坑。很多串口芯片在系统层面只允许一个进程独占访问SSCOM、Arduino IDE 的串口监视器、或者之前开着的调试页面没有正确关闭端口都会导致浏览器这边打开失败报NetworkError或者消息里带 Access Denied。排查顺序关掉所有疑似占用串口的程序。如果是之前网页占用确认旧页面已经关闭最好在任务管理器里确认浏览器进程退出。在设备管理器中确认串口号没有变化。重新打开页面再点连接。Linux 下如果是普通用户打开报权限不足先看ls -l /dev/ttyUSB0的属组再确认自己是否在 dialout 组里不要一上来就 chmod 777。5.4 坑四读写背压没处理好高速数据丢帧串口波特率跑满 115200 时理论上每秒能到大约 11KB看起来不大但如果你在读取循环里做同步的 DOM 操作、字符串拼接、甚至触发图表重绘处理速度跟不上数据到达速度缓冲区会被打爆读到的数据就像被抽帧一样中间缺了一大段。这里有两个层面的优化数据读取循环要时刻追赶拿到 chunk 后只做轻量操作把真正耗时的解析工作放到队列或分片处理中const reader port.readable.getReader(); while (true) { const { value, done } await reader.read(); if (done) break; rawChunks.push(value); // 只入队 scheduleFlush(); // 用 requestAnimationFrame 或定时器批量处理 }写入侧要注意背压。串口是慢设备调用writer.write()后不能连续狂写要等writer.readyconst writer port.writable.getWriter(); await writer.ready; await writer.write(new Uint8Array([0x01, 0x03, 0x00, 0x00, 0x00, 0x01])); writer.releaseLock();5.5 坑五热插拔后的陈旧端口让 open 直接抛异常调试过程中拔掉 USB 线再插回去如果页面没有监听端口断连事件端口对象已经失效再调用open()会抛 InvalidStateError界面上的连接状态也不会自动更新。正确做法是监听全局串口连接和断开事件及时刷新页面状态navigator.serial.addEventListener(connect, (event) { // 刷新端口下拉列表 }); navigator.serial.addEventListener(disconnect, (event) { // 标记对应端口断开清理 UI });同时读取循环里也要 catch 端口断开抛出的错误否则控制台会一直被异常刷屏。热插拔之后重新打开端口要重新requestPort()或者从getPorts()里拿新的端口对象不要复用旧的。我把这类工具的常见报错整理了一下排查时可以直接对照报错信息原因处理方式SecurityError非用户手势调用或非安全上下文放到点击事件回调里使用 HTTPS/localhostNotFoundError用户在设备选择框里取消了选择引导用户重新点击连接InvalidStateError端口已打开、正在关闭或已失效先 close 再 open或重新获取端口NetworkError Access Denied串口被其他程序占用关闭占用程序确认设备未被锁Permission deniedLinux用户不在 dialout 组sudo usermod -aG dialout $USER后重新登录6. 二次开发方向把能用变成好用的调试平台6.1 MQTT/局域网桥接让浏览器脱离 USB 线浏览器串口工具的天然瓶颈是设备必须插在这台电脑上。当设备部署在产线或远端调试人员不可能背着电脑到处跑这时候可以给工具加一个 MQTT 桥接层本机运行一个轻量代理进程负责读取串口数据并转发到 MQTT broker远程同事通过 Web 页面订阅同一主题收发数据就变成了串口设备 - 代理 - MQTT - 浏览器的链路。这个方案我实际搭过一次主要用来远程看现场设备的运行日志。前端代码几乎不用改只要把数据来源抽象成一个接口本地串口和 MQTT 都实现同一个数据源协议即可。6.2 从串口升级到 WebUSB免驱烧录的下一步对支持 WebUSB 的设备比如部分 ESP32-S2/S3 和带有 UF2 bootloader 的开发板可以绕过传统串口驱动直接用 WebUSB 协议完成固件烧录。这意味着浏览器不仅能调试还能刷固件。整体体验非常接近打开网页 - 选设备 - 一键烧录的免驱方案。但要注意 WebUSB 和 Web Serial 不是一回事。WebUSB 获取设备句柄后需要设备固件配合暴露合理的 USB 接口和端点才能完成数据交互。如果你的开发板只是普通 CH340 串口芯片那就还是老老实实走 Web Serial。6.3 PWA 与桌面壳移动端和分发场景的落地调试页面做成一堆静态文件之后打包扩展非常容易。加一个 manifest 和 service worker就能变成 PWAAndroid 手机配合 USB OTG 线也能打开同一套界面调试串口设备不用在手机上装任何 APK。如果团队成员不喜欢用浏览器标签页可以再用 Electron 或 Tauri 套一层壳把同一个静态页面包装成本地应用。前端代码完全复用只有壳层负责打开本地目录、申请系统权限这些事。我建议小团队先走纯网页方案等真的有分发需求时再做壳避免过早引入 Electron 的体积和内存开销。我个人在实际使用中的体会是这类开源 Web 串口调试工具的定位不是取代所有桌面串口助手而是把高频、需要协作、需要可视化的调试场景搬到浏览器里。它最值钱的地方不是那个收发界面而是整个调试环境池化部署一次、打开即用、人人同款。最后再分享一个小技巧如果你经常在多种协议间切换可以把每种协议的常用指令模板和解析规则存成 JSON 工作区配置随项目文档一起提交新人拿到配置导入就能上手省掉一整套口头教学的成本。 
长河君 · 2026/10/8 20:16:59 · 阅读 1.2k Web Serial API实战：浏览器串口调试工具原理与踩坑指南
我电脑里至今躺着一堆串口调试工具SSCOM 在 Windows 上稳minicom 在 Linux 上够用macOS 偶尔还得翻出 screen 现查参数。但每次换电脑、换系统、带团队联调的时候这些本地工具就变成一个很烦人的包袱。直到我系统试了基于 Web Serial API 的开源 Web 串口调试工具——浏览器打开即用Chrome 一开、USB 一插页面里就能看日志、发指令、画波形。这篇就聊聊这类开源的浏览器串口调试方案的底层原理、功能拆解和实战踩坑适合被传统串口助手折腾过的嵌入式开发、硬件调试和 IoT 学习者参考。1. 传统串口助手的三大痛点以及浏览器方案为什么能补上1.1 我桌上为何堆着三四个串口工具干嵌入式的人都有过这种经历项目一开始用 Windows 下的 SSCOM连上开发板收日志功能没问题但换到 Linux 之后就得改用 minicom还要先背一遍minicom -D /dev/ttyUSB0 -b 115200的参数。macOS 上逼急了直接screen /dev/cu.usbserial-xxx 115200但 screen 的串口模式没有滚动缓冲区日志一刷就全没影。更麻烦的是设备多了之后某个串口号被占用你要在设备管理器里一个个认或者用 udevadm 去翻设备节点。这些工具单一场景下都挺好但放在一起就是三座大山安装和依赖隔离在各个操作系统里换环境成本极高。数据不好带走。SSCOM 保存的日志格式、编码、时间戳跟你自己用 minicom 记下来的完全不是一套东西。波形和格式解析基本靠个人。PID 调试时我想直观看到曲线变化传统助手很难直接做到。我后来转向开源的 Web 串口调试工具核心原因不是省一次安装而是它把整个调试环境统一到了浏览器这一个载体里。项目组里任何人打开同一个 URL看到的是同一套收发界面、同一套解析逻辑联调和复现问题时的沟通成本大幅下降。1.2 Web 方案解决的是工程协作问题不只是省一次安装这类工具一般基于 Web Serial API整个应用就是一堆静态文件HTML、CSS、JavaScript。你可以把它扔到内网随便一台静态服务器上团队所有人用 Chrome 或 Edge 打开同一个地址点一下连接按钮就能对着同一款开发板调试。没有安装包不需要配 PATH不需要管 Windows 和 Linux 下的执行文件差异。从前期的原型联调到现场故障排查效率提升主要来自三点环境一致性。你在 chrome 里看到的收发界面同事在 Edge 里看到的一模一样连波特率选项和 Hex 切换逻辑都完全一致。可复用配置。很多 Web 串口工具支持把工作区里的波特率、解析模板、图表字段导出成 JSON文档里附一份拿到任何机器上导入即可。可以嵌进自己的 Web 工程。比如在内部测试平台上挂一个串口调试组件和 CI/CD、设备管理面板联动这是传统桌面助手做不到的。但这里有一个必须说清楚的现实浏览器打开即用指的是应用本身不用安装不代表串口驱动可以省掉。你的 USB 转串口芯片CH340、CP2102、FTDI 这些在系统层面依然要有驱动支持Linux 下还得有 dialout 组权限。浏览器只是把你调驱动的过程藏到了后台底层依赖并没有消失。2. Web Serial API 原理拆解浏览器访问串口的权限链路2.1 硬件层从 USB 到 COM/TTY 的漫长旅程要理解浏览器为什么能碰串口得先搞清楚串口设备在系统里到底是怎么存在的。以最常见的 USB 转串口方案为例开发板上的 UART 引脚经过 CH340 或 CP2102 芯片转换成 USB 信号插入电脑后操作系统通过 USB CDC ACM 协议识别出这是一个通信设备然后加载对应驱动把它映射成一个虚拟串口节点。Windows 里你看到的是 COM3、COM5 这种编号Linux 里是/dev/ttyUSB0或/dev/ttyACM0macOS 里是/dev/cu.usbserial-xxx。所以串口在操作系统眼里就是一个设备文件或者一个驱动抽象的 I/O 通道。浏览器没有能力自己写一个 USB 驱动它做的是在浏览器进程里调用操作系统提供的串口访问接口。Chromium 的串口服务在后台完成对这个设备节点的 open、read、write、设置波特率等底层操作前端 JavaScript 只通过navigator.serial这几个 API 跟它对话。这也是为什么 Web Serial 支持的平台范围完全取决于浏览器而不是取决于你买的是哪家的开发板。2.2 浏览器做了什么navigator.serial 的权限模型前端侧核心 API 并不多但权限模型很关键navigator.serial.requestPort()弹出系统设备选择框让用户手动选一个串口。这个调用必须发生在用户手势里比如点击按钮的事件回调中否则直接报 SecurityError。navigator.serial.getPorts()获取当前页面已经被授权过的端口列表。同源页面再次访问时可以直接拿到之前选过的设备不需要重新弹窗。port.open({ baudRate, dataBits, stopBits, parity, flowControl })按参数打开串口返回 Promise。port.readable一个 ReadableStream通过getReader()拿到底层数据。port.writable一个 WritableStream通过getWriter()写入数据。port.getSignals()和port.setSignals()读取、设置 DTR、RTS 等控制线状态。一个最小可用的打开流程是这样const port await navigator.serial.requestPort(); await port.open({ baudRate: 115200, dataBits: 8, stopBits: 1, parity: none }); const decoder new TextDecoder(); const reader port.readable.getReader(); while (true) { const { value, done } await reader.read(); if (done) break; // 这里拿到的是 Uint8Array需要自己拼帧 processData(decoder.decode(value)); }权限模型的设计逻辑很清楚浏览器不允许网页在后台静默探测你的串口设备每一次访问都必须让你知道。用户可以在浏览器的站点设置里看到这个页面被授予了哪些串口设备的访问权也可以随时撤销。这种每次都要明确授权的交互对开发者来说是一种麻烦但对安全性来说是必要的毕竟串口协议往往没有加密和鉴权。2.3 支持矩阵Chrome/Edge 能用Safari 别想Web Serial API 目前的浏览器支持情况比较干脆主力的 Chromium 系浏览器都行但 Firefox 和 Safari 至今没有默认开放。浏览器支持情况备注Chrome 89完整支持桌面端稳定可用Android 端在 USB OTG 场景也能用Edge 89完整支持内核同为 Chromium体验与 Chrome 一致Opera 76完整支持Chromium 内核Firefox需手动开启 flag默认关闭生产环境不建议依赖Safari / iOS Safari不支持暂无明确计划所以如果你要给团队部署 Web 串口调试工具直接规定用 Chrome 或 Edge 就行这在实际工程中不是大问题因为嵌入式团队基本人手一个 Chromium 浏览器。真正麻烦的是浏览器版本太旧的现场。我的建议是统一升级到较新的版本因为早期实现里 Web Serial 的 API 细节还有一些小变化老版本很容易踩到getPorts()不返回已授权端口之类的坑。3. 开源项目功能拆解一个浏览器串口助手的完整能力地图3.1 核心收发连接管理、按帧读取、Hex/ASCII 切换这类开源项目的典型界面通常就是顶部连接区 中间收发区 底部状态栏的布局。连接区有端口下拉、波特率选择、打开/关闭按钮收发区可以切换 ASCII 和 Hex 显示。按帧读取是我建议大家一定要有的功能。串口数据是字节流没有帧边界你需要根据场景自己拼。最常见的按行读取是切到\n我做过一个定制版本是按固定字节数分包还有一个是每隔 10ms 把缓冲区的数据作为一帧推给前端图表。核心逻辑不复杂但直接决定了数据能不能被正确解析。function parseLineStream(chunk) { buffer chunk; let index; while ((index buffer.indexOf(\n)) 0) { const line buffer.slice(0, index); buffer buffer.slice(index 1); handleLine(line); } }Hex 模式做 Modbus 调试时尤其有用。很多工业仪表、传感器用的是 Modbus RTU你要发一帧01 03 00 00 00 01 84 0A这样的十六进制指令传统助手能发就不错了但 Web 工具可以在前端直接做 CRC16 计算和校验避免手算出错的窘境。我实际调过一个温控器靠的就是浏览器里直接粘贴 Modbus 指令 自动算 CRC比拿计算器一个个按快太多了。3.2 调试利器从日志回放到 PID 实时曲线PID 调试是这类工具最出彩的地方。以前调 PID要么用串口助手的文本刷屏自己脑补曲线要么导出 CSV 后用 Excel 画图来回折腾半天。我把 STM32 和 ESP32 的 PID 运行参数通过串口按 JSON 格式打出来Web 工具里选好字段曲线实时就出来了。MCU 侧只需要简单输出结构化数据{t:1200,kp:2.1,ki:0.05,kd:0.08,set:300,cur:287} {t:1210,kp:2.1,ki:0.05,kd:0.08,set:300,cur:291}前端拿到后按行解析把cur和set分别映射到两条曲线刷新到 Canvas 或 SVG 图表里。调完 Kp 改成 3.5下一秒曲线就能看到超调量变大、振荡周期变短这种反馈速度是文本日志给不了的。日志导出也顺手做了。浏览器里直接把收发的原始数据用 Blob 包一下生成文件下载不依赖任何后端const blob new Blob([logContent], { type: text/plain;charsetutf-8 }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download serial-log.txt; a.click(); URL.revokeObjectURL(url);3.3 工程化细节依赖少、可自托管、可二次开发我复现这套方案时前端技术栈用的是 Vite TypeScript图表只引入一个轻量库加起来没多少依赖。整个项目就是静态资源构建完扔到 nginx、NAS 或者任何静态文件服务里就能跑不需要数据库不需要后端服务省掉了大量运维负担。因为它是纯前端项目二次开发的成本也很低。你可以把它拆成组件嵌到自己的 Web 工程里也可以直接改源码加功能。我见过有人把它接进公司内部的设备测试系统串口数据直接入库还有人基于它做了产线自动化测试的页面。这种一个静态页面解决一个调试场景的思路非常适合中小团队快速落地。4. 从零上手实测ESP32 日志采集与 PID 波形调试全流程4.1 准备环节浏览器、驱动、权限三件事实操之前先把环境扫一遍缺哪一个都跑不通。第一浏览器版本。Chrome 89 以上或 Edge 89 以上这个基本都能达标。检查方法很简单打开一个 HTTPS 页面或者 localhost 页面在控制台输入navigator.serial能出对象就说明支持。第二串口驱动。我用的 ESP32 开发板板载 CH340Windows 下如果插上没反应先去装 CH340 驱动。Linux 下多数发行版自带 CDC ACM 驱动但当前用户必须有 dialout 组权限否则打开设备会报权限不足sudo usermod -aG dialout $USER改完用户组要重新登录一次生效。插上开发板后用ls /dev/ttyUSB*确认设备节点存在。第三安全上下文。Web Serial 只在安全上下文里可用。最简单的方式是本地起一个服务访问http://localhost:5173或http://127.0.0.1:8080localhost 天然算安全上下文。千万不要用局域网 IP 裸 HTTP 访问会被浏览器判定为不安全上下文后面专门讲这个坑。4.2 连接 ESP32一次完整的设备授权过程准备完成后把 ESP32 通过 USB 线插到电脑打开调试页面点击连接按钮。此时浏览器会弹出系统级设备选择窗口列出当前可用的串口设备。我这边显示的是USB-Enhanced-SERIAL CH340旁边会带设备 VID/PID 信息。选完点连接工具内部会调用port.open()打开串口设置 115200 波特率。连接成功后ESP32 的启动日志会直接刷到收发区。这时候就能验证收发链路了在发送框输入一条指令观察开发板是否响应。ESP32 的自动下载电路依赖 DTR 和 RTS 两个控制信号部分 Web 串口工具会在连接时默认置位这两个信号如果你发现点连接后开发板直接进入下载模式而不是正常运行那大概率是 DTR/RTS 状态没设置对。此时需要手动关掉自动下载相关的信号控制或者检查工具是否支持setSignals()的配置。4.3 波形可视化把串口文本变成实况曲线波特率跑通之后我给 ESP32 刷了一个简单的 PID 温控程序让它每 10ms 输出一次控制量和实际温度。在 Web 工具的解析配置里指定 JSON 解析模板把cur字段和set字段加进曲线视图图表立刻开始滚动。调参过程非常直观我把 Kp 从 2.0 提到 3.0曲线从原本的缓升变成了带明显超调的上升峰值甚至冲过了目标线再把 Ki 调小一点稳态误差慢慢收掉。整个过程没有导出过一次文件所有调参反馈都在同一个页面里闭环实测下来一次 PID 整定的时间比传统方式缩短了大半。提示PID 数据采样周期不要太长建议 10ms 到 50ms 一组。采样太稀疏时曲线会丢失振荡细节你会误以为参数很稳实际上系统已经在振荡了。5. 跨浏览器兼容与踩坑实录五个必须提前知道的问题5.1 坑一没在用户手势里调用 requestPort直接 SecurityError第一次我图省事在页面加载完成时自动调用navigator.serial.requestPort()结果控制台直接抛 SecurityError。原因我之前提过Web Serial 的授权必须由用户手势触发。这个限制无法绕过唯一正确的做法就是把requestPort()放进按钮的点击事件回调里。如果你真的要页面一进来就自动连上次设备可以先在后台调用getPorts()拿已授权端口列表。如果拿到了且只有一个直接尝试open()即可这个过程不需要用户手势因为授权已经存在了。如果列表为空再引导用户点击连接按钮。5.2 坑二HTTP 内网地址被浏览器判定为不安全上下文我在内网服务器上部署了一个调试页面同事通过http://192.168.1.10:8080访问结果点击连接没有任何反应控制台报错提示 API 只能在安全上下文中使用。localhost 没问题但局域网 IP 的纯 HTTP 页面不被信任。解决思路有几个部署到带 HTTPS 的网关后面用 nginx 反代加证书。本地开发时用 Chrome 的启动参数临时把某个内网地址标记为安全来源仅限开发阶段chrome --unsafely-treat-insecure-origin-as-securehttp://192.168.1.10:8080如果只是自己用直接访问 localhost 加端口映射也行但团队成员之间协作时这个方案不现实。我的建议是把调试工具部署在内网 HTTPS 网关下当成标准配置一劳永逸。5.3 坑三串口被其他程序独占浏览器报 Access Denied这是 Windows 上最常见的坑。很多串口芯片在系统层面只允许一个进程独占访问SSCOM、Arduino IDE 的串口监视器、或者之前开着的调试页面没有正确关闭端口都会导致浏览器这边打开失败报NetworkError或者消息里带 Access Denied。排查顺序关掉所有疑似占用串口的程序。如果是之前网页占用确认旧页面已经关闭最好在任务管理器里确认浏览器进程退出。在设备管理器中确认串口号没有变化。重新打开页面再点连接。Linux 下如果是普通用户打开报权限不足先看ls -l /dev/ttyUSB0的属组再确认自己是否在 dialout 组里不要一上来就 chmod 777。5.4 坑四读写背压没处理好高速数据丢帧串口波特率跑满 115200 时理论上每秒能到大约 11KB看起来不大但如果你在读取循环里做同步的 DOM 操作、字符串拼接、甚至触发图表重绘处理速度跟不上数据到达速度缓冲区会被打爆读到的数据就像被抽帧一样中间缺了一大段。这里有两个层面的优化数据读取循环要时刻追赶拿到 chunk 后只做轻量操作把真正耗时的解析工作放到队列或分片处理中const reader port.readable.getReader(); while (true) { const { value, done } await reader.read(); if (done) break; rawChunks.push(value); // 只入队 scheduleFlush(); // 用 requestAnimationFrame 或定时器批量处理 }写入侧要注意背压。串口是慢设备调用writer.write()后不能连续狂写要等writer.readyconst writer port.writable.getWriter(); await writer.ready; await writer.write(new Uint8Array([0x01, 0x03, 0x00, 0x00, 0x00, 0x01])); writer.releaseLock();5.5 坑五热插拔后的陈旧端口让 open 直接抛异常调试过程中拔掉 USB 线再插回去如果页面没有监听端口断连事件端口对象已经失效再调用open()会抛 InvalidStateError界面上的连接状态也不会自动更新。正确做法是监听全局串口连接和断开事件及时刷新页面状态navigator.serial.addEventListener(connect, (event) { // 刷新端口下拉列表 }); navigator.serial.addEventListener(disconnect, (event) { // 标记对应端口断开清理 UI });同时读取循环里也要 catch 端口断开抛出的错误否则控制台会一直被异常刷屏。热插拔之后重新打开端口要重新requestPort()或者从getPorts()里拿新的端口对象不要复用旧的。我把这类工具的常见报错整理了一下排查时可以直接对照报错信息原因处理方式SecurityError非用户手势调用或非安全上下文放到点击事件回调里使用 HTTPS/localhostNotFoundError用户在设备选择框里取消了选择引导用户重新点击连接InvalidStateError端口已打开、正在关闭或已失效先 close 再 open或重新获取端口NetworkError Access Denied串口被其他程序占用关闭占用程序确认设备未被锁Permission deniedLinux用户不在 dialout 组sudo usermod -aG dialout $USER后重新登录6. 二次开发方向把能用变成好用的调试平台6.1 MQTT/局域网桥接让浏览器脱离 USB 线浏览器串口工具的天然瓶颈是设备必须插在这台电脑上。当设备部署在产线或远端调试人员不可能背着电脑到处跑这时候可以给工具加一个 MQTT 桥接层本机运行一个轻量代理进程负责读取串口数据并转发到 MQTT broker远程同事通过 Web 页面订阅同一主题收发数据就变成了串口设备 - 代理 - MQTT - 浏览器的链路。这个方案我实际搭过一次主要用来远程看现场设备的运行日志。前端代码几乎不用改只要把数据来源抽象成一个接口本地串口和 MQTT 都实现同一个数据源协议即可。6.2 从串口升级到 WebUSB免驱烧录的下一步对支持 WebUSB 的设备比如部分 ESP32-S2/S3 和带有 UF2 bootloader 的开发板可以绕过传统串口驱动直接用 WebUSB 协议完成固件烧录。这意味着浏览器不仅能调试还能刷固件。整体体验非常接近打开网页 - 选设备 - 一键烧录的免驱方案。但要注意 WebUSB 和 Web Serial 不是一回事。WebUSB 获取设备句柄后需要设备固件配合暴露合理的 USB 接口和端点才能完成数据交互。如果你的开发板只是普通 CH340 串口芯片那就还是老老实实走 Web Serial。6.3 PWA 与桌面壳移动端和分发场景的落地调试页面做成一堆静态文件之后打包扩展非常容易。加一个 manifest 和 service worker就能变成 PWAAndroid 手机配合 USB OTG 线也能打开同一套界面调试串口设备不用在手机上装任何 APK。如果团队成员不喜欢用浏览器标签页可以再用 Electron 或 Tauri 套一层壳把同一个静态页面包装成本地应用。前端代码完全复用只有壳层负责打开本地目录、申请系统权限这些事。我建议小团队先走纯网页方案等真的有分发需求时再做壳避免过早引入 Electron 的体积和内存开销。我个人在实际使用中的体会是这类开源 Web 串口调试工具的定位不是取代所有桌面串口助手而是把高频、需要协作、需要可视化的调试场景搬到浏览器里。它最值钱的地方不是那个收发界面而是整个调试环境池化部署一次、打开即用、人人同款。最后再分享一个小技巧如果你经常在多种协议间切换可以把每种协议的常用指令模板和解析规则存成 JSON 工作区配置随项目文档一起提交新人拿到配置导入就能上手省掉一整套口头教学的成本。