★ FEATURED ARTICLE 1. 为什么要在浏览器里直接跟串口打交道第一次听说 Web Serial API 的人十有八九会反问一句串口通信不是上位机软件的活儿吗浏览器凑什么热闹我当初也是这个反应。早些年做硬件调试桌面上永远开着两三个串口助手换一台电脑就得重新装驱动、配环境客户现场演示时最怕遇到这台机器没装工具的尴尬。Web Serial API 解决的正是这个痛点——它把串口读写能力直接做进了浏览器只要打开一个网页插上设备就能通信不用装任何客户端。这个能力的核心价值在于零安装、跨平台、易分发。你写好的调试页面往服务器上一放同事、客户、测试人员打开链接就能用Windows、macOS、Linux 通吃连手机上的部分浏览器都能跑。对于做嵌入式、物联网、工控、教育硬件的人来说这意味着可以把工具变成链接。它适合谁我梳理了三类人一是硬件工程师想快速做个可视化调试面板二是前端开发者被要求做设备配置页面却不知道怎么碰硬件三是创客和教学场景需要让学生用最少的步骤看到串口数据。这篇文章我会从原理讲到实操把踩过的坑、参数怎么算、代码怎么写全部摊开讲读完你就能自己搭一个能用的网页串口工具。需要先明确一个前提Web Serial API 目前主要在基于 Chromium 内核的浏览器上可用而且必须在安全上下文HTTPS 或 localhost下才能调用。这不是限制而是安全设计——串口是能直接操作硬件的接口浏览器不敢让任意 HTTP 页面随便访问。理解这一点后面很多为什么报错就迎刃而解了。2. Web Serial API 的能力边界与底层机制2.1 它到底能做什么不能做什么很多人一上来就问能不能用它烧录固件。我的回答是能传数据但不适合干重活。Web Serial API 提供的是字节流的读写能力你可以发送任意二进制数据理论上烧录协议也能跑但浏览器环境的性能、内存管理和中断处理都不如原生工具烧录这种对时序敏感的操作还是交给专业软件稳妥。它的典型适用场景我列了个表方便你对照判断场景类型是否适合原因说明设备参数配置非常适合数据量小交互式操作网页表单天然合适实时数据监控适合配合图表库可做实时曲线刷新率够用日志抓取导出适合读到的数据可直接存成文件下载固件烧录不推荐时序敏感浏览器调度不可控高速数据采集受限受 JS 单线程和事件循环影响高波特率下易丢包长时间无人值守谨慎页面休眠、标签页切换可能中断连接这张表是我实际项目里总结出来的不是照搬文档。尤其是最后一条我吃过亏一个监控页面挂在后台标签页跑了半小时回来发现数据断了原因是浏览器对后台标签页做了节流。后面会讲怎么缓解。2.2 串口通信的基本原理用大白话讲清楚串口通信本质上是两个设备按照约定好的速度一位一位地传数据。你可以把它想象成两个人用摩尔斯电码对话约定好每秒敲几下波特率什么时候开始起始位什么时候结束停止位要不要校验校验位。这几个参数必须双方完全一致否则收到的就是乱码。关键参数有这么几个波特率Baud Rate每秒传输的符号数常见 9600、115200。双方必须一致这是最常见的收不到数据原因。数据位Data Bits通常 8 位表示每个字符用几位传。停止位Stop Bits通常 1 位标记一个字符结束。校验位Paritynone、even、odd用于简单检错很多设备不用。流控Flow Controlnone、hardware、software控制发送节奏防止缓冲区溢出。在 Web Serial API 里这些参数通过一个配置对象一次性传给port.open()。我建议你永远显式指定所有参数不要依赖默认值因为不同设备的默认值可能不一样显式写出来能省掉大量排查时间。2.3 浏览器安全模型带来的三个约束Web Serial API 不是想调就能调的它受浏览器安全模型约束我总结了三条必须记住的规则第一必须由用户手势触发。也就是说navigator.serial.requestPort()这个调用必须放在按钮点击之类的事件处理函数里不能在页面加载时自动执行。这是防止恶意网页偷偷扫描你连了什么设备。第二必须安全上下文。HTTPS 或者 localhost 才行。本地开发用localhost没问题部署到服务器就必须上 HTTPS。我见过有人用 IP 地址直接访问结果 API 根本不存在折腾半天才发现是这个原因。第三权限是持久的但可撤销。用户授权某个设备后下次访问同一站点可以不用再选但用户随时能在浏览器设置里撤销。你的代码要能处理权限被撤销的情况不能假设授权一直有效。提示调试时如果navigator.serial是undefined先检查是不是 HTTPS/localhost再检查浏览器版本最后检查是不是被企业策略禁用了。这三步能解决九成的API 不存在问题。3. 从零搭一个能跑的网页串口工具3.1 环境准备与最小可用页面先说环境。你只需要一个现代浏览器Chromium 内核版本 89 以上比较稳和一个文本编辑器。不需要 Node.js不需要构建工具一个 HTML 文件就能跑起来。这对硬件工程师特别友好不用碰前端那套复杂的工程化。最小可用页面的结构是这样一个按钮用来触发设备选择一个区域显示接收到的数据一个输入框加按钮用来发送数据。我先把骨架写出来!DOCTYPE html html langzh-CN head meta charsetUTF-8 title网页串口工具/title /head body button idconnectBtn连接串口/button button iddisconnectBtn disabled断开/button div idoutput/div input idsendInput placeholder输入要发送的内容 button idsendBtn disabled发送/button script srcserial.js/script /body /html这个骨架故意做得极简是为了让你先跑通流程再逐步加功能。我见过太多人一上来就套框架结果连为什么连不上都定位不了。先用最朴素的方式验证通路是硬件调试的铁律。3.2 连接设备requestPort 的正确打开方式连接的核心是navigator.serial.requestPort()。它返回一个 Promiseresolve 出来的是用户选中的串口对象。注意这个调用会弹出浏览器的设备选择框用户不选就会一直挂着所以要做好交互反馈。let port null; let reader null; let writer null; async function connect() { try { port await navigator.serial.requestPort(); await port.open({ baudRate: 115200, dataBits: 8, stopBits: 1, parity: none, flowControl: none }); console.log(串口已打开); startReading(); } catch (err) { console.error(连接失败:, err); } }这里有几个细节值得展开。波特率我写死成 115200实际项目里应该做成下拉框让用户选因为不同设备差异很大。port.open()的参数对象里baudRate是唯一必填的其他都有默认值但我前面说了显式写全更稳。还有一个容易忽略的点同一个串口不能被两个页面同时打开。如果你调试时发现open报错说端口被占用先检查是不是另一个标签页还连着。这个错误信息有时候很含糊我踩过好几次。3.3 读取数据ReadableStream 的循环陷阱读取数据用的是port.readable它是一个 ReadableStream。标准写法是拿一个 reader然后循环read()async function startReading() { reader port.readable.getReader(); try { while (true) { const { value, done } await reader.read(); if (done) break; if (value) { displayData(value); } } } catch (err) { console.error(读取错误:, err); } finally { reader.releaseLock(); } }这段代码看着简单但坑就在while(true)里。当你想断开连接时如果直接调port.close()这个循环还在await reader.read()上挂着会抛异常。正确做法是先reader.cancel()让read()返回done: true循环自然退出再关端口。我第一次写的时候没处理这个断开按钮点了没反应查了半天。另外value是Uint8Array不是字符串。要显示成文本得用TextDecoder解码const decoder new TextDecoder(); function displayData(bytes) { const text decoder.decode(bytes); document.getElementById(output).textContent text; }如果你的设备发的是二进制协议就别解码成文本了直接按字节处理。文本还是二进制取决于你的设备协议这个判断要在写代码前就确定。3.4 发送数据Writer 的加锁与释放发送数据用port.writable拿一个 writer 写进去async function sendData(text) { if (!port || !port.writable) return; const writer port.writable.getWriter(); const encoder new TextEncoder(); await writer.write(encoder.encode(text)); writer.releaseLock(); }这里的关键是releaseLock()必须调用。writer 是独占的你不释放下次getWriter()就会报错说流被锁住了。我建议把发送封装成一个函数每次用完立刻释放不要长期持有 writer。有人为了性能把 writer 缓存起来结果遇到各种锁冲突得不偿失。还有一个细节发送时要不要加换行符。很多设备尤其是用 AT 指令的模块要求命令以\r\n结尾。这个不是 API 的事是协议的事你得看设备手册。我一般会在发送框旁边加个追加换行的勾选项灵活应对。4. 实测中那些文档不会告诉你的坑4.1 后台标签页节流导致的数据中断这是我踩过最深的坑。一个数据监控页面前台跑得好好的切到别的标签页十分钟后回来发现数据断了而且没有任何报错。原因是浏览器对后台标签页做了定时器和任务节流read()循环被冻住了。缓解办法有几个我按推荐程度排序用 Web Worker 承载读取逻辑。Worker 的节流策略比主线程宽松能显著降低中断概率。这是最靠谱的方案但代码复杂度上去了。加心跳检测。定时检查最后一次收到数据的时间超过阈值就提示用户页面可能被挂起。提示用户保持页面在前台。最土但最有效适合内部工具。我现在的做法是内部调试工具就用提示正式产品上 Worker。不要指望浏览器会一直给你满速跑后台任务这是设计使然不是 bug。4.2 波特率不匹配时的乱码排查链路收到乱码是最常见的求助。我的排查顺序是这样的确认双方波特率一致。这是第一嫌疑占七成以上。设备手册写的和实际固件里设的可能不一样。确认数据位、停止位、校验位一致。有些老设备用 7 位数据位或偶校验容易被忽略。确认编码方式。如果设备发的是 GBK 中文你用 UTF-8 解码就是乱码。这种情况要换TextDecoder(gbk)。确认电平标准。TTL 和 RS232 电平不一样中间需要转换芯片接错了要么没数据要么烧口。我做过一个表格贴在工位上每次乱码就照着过一遍比瞎试快得多。排查要有顺序从概率最高的原因开始不要东一榔头西一棒子。4.3 断开重连时的资源清理断开连接看着简单其实要清理的东西不少reader 要 cancel 并 releaseLockwriter 要确保已释放port 要 close。漏掉任何一步下次重连就可能失败。async function disconnect() { if (reader) { await reader.cancel(); reader.releaseLock(); reader null; } if (port) { await port.close(); port null; } }我把这段封装成一个函数所有断开路径都走它。资源清理要集中管理散落在各处迟早会漏。另外页面卸载时beforeunload事件也要调一次防止用户直接关页面导致端口没释放。4.4 设备热插拔的监听处理用户拔掉设备再插上你的页面得知道。Web Serial API 提供了connect和disconnect事件navigator.serial.addEventListener(disconnect, (e) { if (e.target port) { console.log(设备已断开); // 更新 UI清理状态 } });注意disconnect事件触发后你的 reader 循环会收到done: true或抛异常要处理好。我见过页面在设备拔掉后卡死的情况就是因为没监听这个事件UI 还显示已连接用户一脸懵。热插拔是硬件场景的常态必须当成一等公民对待。5. 把工具做得更好用的几个进阶思路5.1 用 Web Worker 隔离读取逻辑前面提到 Worker 能缓解后台节流具体怎么做把port对象传给 Worker 是不行的串口对象不能跨线程传递。可行的方案是在主线程读取把数据 postMessage 给 Worker 做处理或者反过来让 Worker 负责解析和存储主线程只管读。真正能减轻节流的是把耗时计算放到 Worker让主线程的读取循环尽量轻。如果你的场景是高频数据加实时解析这个优化很有价值。我做过一个每秒上千帧的采集主线程解析直接卡死挪到 Worker 后流畅多了。5.2 数据可视化与导出光看文本流不够直观加个实时曲线会好用很多。可以用 Canvas 自己画也可以引入轻量图表库。数据导出方面把接收到的内容拼成字符串用 Blob 加URL.createObjectURL就能触发下载function exportLog(text) { const blob new Blob([text], { type: text/plain }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download serial-log.txt; a.click(); URL.revokeObjectURL(url); }这个功能在抓日志时特别实用客户现场抓完直接下载发回来比截图靠谱多了。5.3 多设备同时连接的可行性一个页面能不能连多个串口可以。requestPort()每次调用让用户选一个设备你可以维护一个端口数组。但要注意每个端口都要独立的 reader 和 writerUI 上也要能区分是哪个设备的数据。我做过一个双设备对传的测试工具一个发一个收用来验证协议挺方便。不过设备一多UI 复杂度上升很快建议按需做。5.4 兼容性兜底与降级提示不是所有浏览器都支持Safari 和 Firefox 目前就不行。所以页面加载时要检测if (!(serial in navigator)) { alert(当前浏览器不支持 Web Serial API请使用基于 Chromium 内核的浏览器); }这个提示要做得友好告诉用户换什么浏览器而不是甩一句不支持就完事。好的降级提示能省掉大量客服成本这是我做面向客户的产品时最深的体会。6. 我在实际项目里攒下的几条经验先说选型。如果你的项目只是内部调试用一个 HTML 文件加原生 JS 就够了别上框架维护成本低。如果要做成正式产品给客户用那要考虑状态管理、错误处理、UI 一致性这时候再引入框架不迟。技术选型要匹配场景不要为了用而用。再说调试。串口调试最有效的工具其实是另一端的日志。浏览器这边收到乱码你光看浏览器没用得看设备到底发了什么。我习惯在设备端也加打印两边对照问题定位快一倍。还有用逻辑分析仪抓一次波形胜过瞎猜一小时尤其是时序相关的问题。最后说心态。串口通信涉及硬件、驱动、协议、浏览器四层任何一层出问题都表现为收不到数据。这时候最忌讳的是乱改代码。我的做法是分层验证先用专业串口工具确认硬件和驱动没问题再用最简网页确认 API 通路最后才上业务逻辑。一层一层排除比同时怀疑所有环节高效得多。这个方向后续还能扩展不少比如结合 WebUSB 做更底层的设备控制或者把串口数据接入 WebSocket 做远程监控。但那是另一个话题了把 Web Serial 这一块吃透已经能解决大部分浏览器连硬件的需求。
阅读完成 · 觉得有帮助？
