macOS 部署与集成指南

三端客户端对照

终端用户安装（dmg）

首次打开与 Gatekeeper

macOS 可能提示「无法验证开发者」或阻止打开。可按以下方式处理：

1. 在 Finder 中右键应用 →「打开」，确认后再次启动。
2. 或前往「系统设置 → 隐私与安全性」，在安全性区域点击「仍要打开」。
3. 企业环境可通过 MDM 将应用加入白名单，避免每台终端重复操作。

前端接入（与 Win/Linux 相同 API）

macOS 终端上的浏览器页面与 Windows、Linux 使用完全相同的 npm 包与调用方式：

npm install web-print-pdf

最小可运行示例（在客户端已启动的前提下）：

import webPrintPdf from 'web-print-pdf';

// 1. 确认本地 WS 服务可用
const status = await webPrintPdf.utils.getConnectStatus();
if (!status.success) {
  throw new Error('请先启动 Web打印专家客户端');
}

// 2. 获取 macOS 上已安装的打印机（CUPS 名称）
const printers = await webPrintPdf.utils.getPrinterList();
const list = printers.data ?? printers;
console.log(list);

// 3. 静默打印 HTML
await webPrintPdf.printHtml(
  '<h1>出库单</h1><p>单号：SO-20260624</p>',
  { paperFormat: 'A4', margin: { top: '10mm', bottom: '10mm' } },
  { printerName: (list[0] && list[0].name) || '默认打印机', copies: 1 }
);

本地服务地址为 ws://127.0.0.1:{端口}/websocket/standard，端口以客户端界面显示为准。web-print-pdf 默认自动连接，无需在代码里写死端口。

macOS 打印栈说明

处理链路与 Windows / Linux 一致，差异仅在出纸阶段：

• 浏览器调用 printHtml → npm 包经本地 WebSocket 提交任务
• 客户端内置 Chromium 内核渲染 HTML → 生成 PDF
• 经 CUPS 投递至「系统设置 → 打印机与扫描仪」中已添加的打印机

若打印机未出现在列表中，请先在 macOS 系统设置中添加网络或 USB 打印机，再在客户端内刷新打印机列表。

常见问题排查

部署要点