需启用Chrome实验性功能、通过网页触发授权、检查站点权限、确保安全上下文(HTTPS/localhost)、验证navigator.serial可用性。

如果您在使用谷歌浏览器访问支持 Web Serial API 的网页时,无法建立与串行设备(如 Arduino、ESP32 等)的连接,则可能是由于 Web Serial 权限未被授予或相关功能未启用。以下是开启网页端串行端口通信并完成 WebSerial 授权的具体操作步骤:
一、确认浏览器版本与启用实验性功能
Web Serial API 默认仅在 Chrome 89 及以上版本中可用,且需确保启用相关实验性标志。该步骤用于激活底层接口支持,使 navigator.serial 对象可被网页调用。
1、在 Chrome 地址栏输入 chrome://flags 并回车进入实验性功能页面。
2、在搜索框中输入 Web Serial,定位到 “Enable Web Serial API” 选项。
3、点击右侧下拉菜单,选择 Enabled。
4、点击页面右下角的 Relaunch 按钮重启浏览器。
二、通过网页触发串行端口选择器授权
Web Serial API 不允许网页自动连接串行设备,必须由用户主动触发请求并手动选择设备。该步骤通过调用 requestPort() 方法唤起系统级设备选择弹窗,完成首次权限授予。
1、访问已集成 Web Serial 功能的网页(例如官方示例页 https://webserial.dev)。
2、点击网页上标有 “Connect to serial device” 或类似文字的按钮。
3、在弹出的设备选择窗口中,勾选 Remember this decision for future visits(如需持久化授权)。
4、从列表中选择目标串行设备(如 “Arduino Uno”、“CP2102 USB to UART Bridge Controller”),点击 Connect。
三、检查网站权限设置
Chrome 将 Web Serial 权限按站点独立存储。若之前拒绝过授权或清除过站点数据,需手动重置该域名的串行端口权限,否则 requestPort() 将直接失败。
1、在当前网页地址栏左侧点击锁形图标 ?。
2、点击 Site settings 进入权限管理页。
3、向下滚动至 Permissions 区域,找到 Serial ports 项。
4、点击右侧箭头展开,将状态设为 Allow;若显示 “Blocked”,则点击 Reset permissions 后刷新页面。
四、启用安全上下文强制要求
Web Serial API 仅在安全上下文(HTTPS 或 localhost)中可用。若网页部署在 HTTP 协议下的非本地域名,navigator.serial 将为 undefined,授权流程无法启动。
1、确认当前网页 URL 以 https:// 或 http://localhost 开头。
2、若为本地开发,可使用 Python 快速启动 HTTPS 服务:执行 python3 -m http.server 8000 --bind 127.0.0.1 后访问 http://localhost:8000。
3、若需 HTTPS 测试,使用 mkcert 工具生成本地可信证书,并配合 serve 命令启动 HTTPS 服务。
五、验证串行对象可用性与调试控制台
开发者可通过浏览器控制台快速判断 Web Serial 是否就绪。该步骤用于确认 API 可调用且无运行时错误,便于定位前端代码问题。
1、在网页中按 F12 打开开发者工具,切换到 Console 标签页。
2、输入 navigator.serial 并回车,应返回一个 Serial 对象而非 undefined。
3、输入 navigator.serial.getPorts() 查看已授权设备列表,返回 Promise,可追加 .then(ports => console.log(ports)) 查看结果。
4、若控制台报错 SecurityError: Permission denied,说明尚未完成授权或安全上下文不满足。











