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)

  1. 从 下载页 获取 macOS dmg 安装包。
  2. 双击 dmg,将「Web打印专家」拖入「应用程序」文件夹。
  3. 从启动台打开客户端,完成初始配置并确认本地打印服务正常运行。
  4. 在前端项目中 npm install web-print-pdf,与 Windows / Linux 使用相同 API。
项说明
安装方式打开 dmg,拖入「应用程序」
芯片架构Apple Silicon(M 系列)与 Intel 均支持
系统版本macOS 11 Big Sur 及以上
启动启动台或「应用程序」文件夹中打开

首次打开与 Gatekeeper

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

  1. 在 Finder 中右键应用 →「打开」,确认后再次启动。
  2. 或前往「系统设置 → 隐私与安全性」,在安全性区域点击「仍要打开」。
  3. 企业环境可通过 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 版策略一致。
免费下载 macOS 客户端 开发文档