WebSocket 连接失败排障指南

浏览器提示无法连接本地客户端时,多为客户端未启动、端口被占用或安全软件拦截。本文按现象对照排查,配合 错误处理标准 统一提示文案。

常见现象

现象常见原因
getConnectStatus 为 false客户端未运行
连接超时防火墙/杀软拦截 127.0.0.1
偶发断开客户端休眠、端口变更
仅某浏览器失败扩展拦截 WebSocket

排查步骤

  1. 确认客户端已启动,托盘/菜单可见
  2. 核对客户端界面端口,默认 ws://127.0.0.1:{port}/websocket/standard
  3. 临时关闭防火墙/杀软测试
  4. 换 Chrome/Edge 排除扩展
  5. 调用 getConnectStatus 与 formatPrintError 记录日志
  6. 仍失败见 Windows 部署 / Linux 部署

预防建议

  • 开机自启客户端(门店/仓库)
  • 内网文档写死「先连客户端再点打印」
  • 远程场景见 remote-print 通道配置

延伸阅读

常见问题

端口会变吗?

以客户端 UI 为准;web-print-pdf 默认自动发现,一般无需写死。

https 页面连 ws 可以吗?

本地 127.0.0.1 WebSocket 通常可用;混合内容策略视浏览器而定。

Docker 内前端能连吗?

客户端须在用户 PC 宿主机,不在容器内。

远程打印也走 WebSocket吗?

远程打印:不调 npm,服务端按固定格式入队并暴露消费接口,工位客户端填该 URL。见 remote-print。

如何给用户友好提示?

统一 formatPrintError,见 error-handling 专题。

各平台客户端部署

同一套 web-print-pdf 前端代码可在 Windows、macOS、Linux/信创混合环境运行;请按终端操作系统安装对应客户端。

免费下载客户端 查看 npm 包 开发文档