联调 Web 静默打印时最折磨人的不是报错而是「API 返回成功 / 没报错但打印机没反应」。本文按从前端到本机客户端再到系统打印栈的顺序给出可操作的排查步骤适用于web-print-pdfWeb打印专家方案。资源链接官网http://webprintpdf.com/客户端下载http://webprintpdf.com/downloadApp/npm 包https://www.npmjs.com/package/web-print-pdfGitHubhttps://github.com/weixiaoyi/web-print-pdf1. 先定位卡在哪一层[1] 浏览器 / web-print-pdf WebSocket 是否连通 [2] Web打印专家 HTML→PDF 是否成功 [3] 打印子进程 Sumatra(lp) 是否执行 [4] 系统打印队列 作业是否进入 spooler [5] 物理设备 卡纸 / 缺纸 / 离线原则从[1] 往上问不要一上来重装驱动。2. 第一层WebSocket 与客户端2.1 现象前端报错连接失败 / timeoutgetPrinterList()调不通2.2 排查检查项命令 / 操作客户端是否运行托盘 / 任务栏是否有Web打印专家端口默认16794备选16805、19235防火墙是否拦截本机127.0.0.1回环多开旧进程占端口杀死后重启客户端2.3 处理完全退出客户端含托盘后重新打开打开客户端「打印测试」浏览器 F12 看 WebSocket 是否连上ws://127.0.0.1:.../websocket/standard3. 第二层API 报错但信息模糊3.1 看客户端日志Web打印专家 提供打印日志 / PDF 日志 / HTML 日志API按时间戳查最近一次任务success: false→ 看msg字段有 queue 耗时 → 卡在排队还是执行3.2 常见 message 对照msg / 现象含义WebSocket 连接失败客户端未启动打印核心组件不存在WindowsSumatra 组件缺失需重装客户端printing exited with exit code打印子进程失败见 §5PrintToDevice: failed打印机名错误或设备不可用Windowslpstat 失败macOS / LinuxCUPS 未运行PDF 引擎缺失macOSheadless_shell 不完整重装对应架构包4. 第三层printerName 问题最高频4.1 现象API 失败或成功但打到了别的机Windows 中文名乱码4.2 排查永远用动态列表不要硬编码constprintersawaitwebPrintPdf.getPrinterList();console.table(printers.map(p({name:p.name,default:p.default})));系统本地核对方式Windows控制面板 / 设置 → 打印机名称macOS / Linux终端lpstat -a或lpstat -p统信 / 麒麟打印管理 lpstat -a4.3 注意名称空格、大小写、URL 编码%20必须一致Windows 侧客户端会做canonical 名纠正乱码修复仍建议以getPrinterList()为准省略printerName时使用系统默认打印机——确认默认机是否正确5. 第四层PDF 有了打印进程失败5.1 WindowsSumatraPDF 链路典型命令形态printPDF64.exe -print-to printer -silent -print-settings ... file.pdf现象原因处理exit code ≠ 0 PrintToDevice failed打印机不存在 / 离线核对 printerName看设备和打印机队列超时 kill队列里有卡住的任务打开系统打印队列删除阻塞作业PDF 打不开文件损坏 / 加密客户端会尝试解密检测换简单 PDF 试客户端在打印子进程CPU 长期 0 且超时时会强制 kill并提示检查打印机异常任务——此时去系统队列清卡死作业。5.2 macOS / 统信 / 麒麟CUPS / lplpstat-r# scheduler 是否 runninglpstat-a# 队列列表lpstat-o# 当前作业lp-d队列名 测试.pdf# 手动试打现象原因处理lpstat -r 失败cupsd 未运行启动打印服务 / 添加打印机lp 报错 unknown printer队列名错误与 lpstat -a 对齐作业 pending 不动驱动 / 网络打印机离线lpstat -o看 reason引擎报错macOS 安装包缺 headless_shell重装对应 arm64/x64 客户端6. 第五层HTML / PDF 阶段问题6.1 现象打出空白页中文豆腐块版式与浏览器预览不一致6.2 排查原因处理未设printBackground: true背景色 / 背景图不打印依赖外链 CSS / 字体改为内联样式终端安装字体页面未加载完就 printHtmlByUrl增大extraOptions.requestTimeout内网需登录传cookies/httpHeaders打印区域未适配使用media print或客户端注入的_printMode_localStorage联调建议先extraOptions.action preview确认 PDF 版式再改print。7. 第六层批量打印特有现象原因整批失败batchPrint 中 task 的action不一致只出前几张后续 HTML 空 / URL 超时顺序错乱batch 内并行生成非严格串行见《batchPrint 从入门到排坑》05 篇。8. 第七层物理设备与驱动当系统打印队列里已有作业但打印机没动静打印机是否脱机 / 休眠 / 缺纸 / 卡纸USB 线 / 网络是否通是否打到了「Microsoft Print to PDF」等虚拟队列驱动是否匹配尤其国产系统 小众型号重启打印 spooler 或 cupsd运维操作需权限9. 一张故障决策树可贴墙打印没反应 │ ├─ getPrinterList 失败 │ └─ 是 → 启动 Web打印专家查 WebSocket / 端口 │ ├─ API 直接 reject │ └─ 看 msg → §3 对照表 │ ├─ 客户端日志 successfalse │ ├─ PDF 阶段失败 → §6 HTML/字体/超时 │ └─ 打印阶段失败 → §5 printerName / 队列 │ ├─ 日志 successtrue 仍无纸 │ ├─ 系统队列无作业 → printerName 错或静默打到虚拟打印机 │ └─ 队列有作业不出 → §8 设备/驱动 │ └─ 批量部分失败 → §7 batchPrint 规则10. 预防性最佳实践实践说明上线前 PoC目标 OS 目标打印机型号实机打 10 次动态 printerName从getPrinterList()取不硬编码先 preview 后 print版式与 PDF 阶段分离验收客户端打印测试每终端部署后先点内置测试日志留存业务侧记录 print 请求 id 与客户端返回 id队列巡检卡死作业定期清理11. 小结「连上了却不出纸」很少是单一原因先确认Web打印专家在跑、WebSocket 通再查printerName 与系统队列名一致然后看客户端日志卡在 PDF 还是打印最后查系统 spooler / CUPS 作业与物理设备按层排查大多数问题可以在 15 分钟内定位。仍无法解决时带着操作系统版本、打印机型号、一次失败任务的客户端日志 msg到官网 http://webprintpdf.com/ 联系技术支持比「打印不了」有效得多。