macOS 部署与集成指南
在 macOS 11+(Apple Silicon / Intel)上部署 Web打印专家客户端,并接入 web-print-pdf 实现网页静默打印与 HTML 转 PDF。与 Windows、Linux 版 API 完全一致,便于混合办公环境统一前端代码。
三端客户端对照
| 版本 | 平台 | 打印后端 | 安装包 |
|---|---|---|---|
| Windows 版 | Windows 10/11 | 内置静默打印引擎 | .exe |
| Linux 版 | x64 / arm64 | 系统标准打印服务 | .deb / .rpm |
| macOS 版 | macOS 11+ | CUPS | .dmg |
官网提供 Windows、Linux、macOS 三套客户端,安装包形态不同,但对外暴露同一套 WebSocket API(/websocket/standard),前端 web-print-pdf 代码无需区分平台。
终端用户安装(dmg)
- 从 下载页 获取 macOS dmg 安装包。
- 双击 dmg,将「Web打印专家」拖入「应用程序」文件夹。
- 从启动台打开客户端,完成初始配置并确认本地打印服务正常运行。
- 在前端项目中
npm install web-print-pdf,与 Windows / Linux 使用相同 API。
| 项 | 说明 |
|---|---|
| 安装方式 | 打开 dmg,拖入「应用程序」 |
| 芯片架构 | Apple Silicon(M 系列)与 Intel 均支持 |
| 系统版本 | macOS 11 Big Sur 及以上 |
| 启动 | 启动台或「应用程序」文件夹中打开 |
首次打开与 Gatekeeper
macOS 可能提示「无法验证开发者」或阻止打开。可按以下方式处理:
- 在 Finder 中右键应用 →「打开」,确认后再次启动。
- 或前往「系统设置 → 隐私与安全性」,在安全性区域点击「仍要打开」。
- 企业环境可通过 MDM 将应用加入白名单,避免每台终端重复操作。
日常运行客户端无需 root 权限;请保持应用在「应用程序」目录,避免从只读挂载的 dmg 内直接运行。
前端接入(与 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) || 'Default printer', copies: 1 }
);
本地服务地址为 ws://127.0.0.1:{端口}/websocket/standard,端口以客户端界面显示为准。web-print-pdf 默认自动连接,无需在代码里写死端口。
macOS 打印栈说明
处理链路与 Windows / Linux 一致,差异仅在出纸阶段:
- 浏览器调用
printHtml→ npm 包经本地 WebSocket 提交任务 - 客户端内置 Chromium 内核渲染 HTML → 生成 PDF
- 经 CUPS 投递至「系统设置 → 打印机与扫描仪」中已添加的打印机
若打印机未出现在列表中,请先在 macOS 系统设置中添加网络或 USB 打印机,再在客户端内刷新打印机列表。
常见问题排查
| 现象 | 处理建议 |
|---|---|
| npm 报连接失败 | 确认客户端已启动;检查防火墙是否拦截本机回环端口 |
| 中文 PDF 缺字 | 在 HTML 中指定常见中文字体,或确保系统已安装对应字体 |
| 打印无反应 | 在系统「打印机与扫描仪」中测试页能否正常出纸;核对 printerName 与 CUPS 队列名称一致 |
| 混合办公环境 | Mac 与 Win/Linux 共用同一套 web-print-pdf 代码,仅终端需分别安装对应客户端 |
部署要点
- macOS 与 Windows、Linux 可共用同一套前端打印代码,适合设计、运营团队使用 Mac 而生产系统跑在 Win/Linux 的场景。
- 内网环境无需外网,HTML 转 PDF 在本地客户端完成。
- 客户端内置「运行示例」页面,可在 Mac 上直接调试各 API 与打印机列表。
- macOS 客户端支持检查更新,与 Windows / Linux 版策略一致。