PrintBridge

中文

English

中文

English

Appearance

快速开始 ​

这一页从下载安装到完成第一单打印，帮你确认 PrintBridge Agent、白名单和 SDK 都已经连通。

为什么需要 PrintBridge ​

现代浏览器不能直接访问本地打印机。

PrintBridge 在你的 Web 应用和打印机之间提供一个安全的本机打印代理。

和传统 Web 打印控件的区别 ​

PrintBridge 不是传统意义上的 Web 打印控件。C-Lodop / Lodop 更擅长打印设计、套打、表格、条码和页面内容打印；PrintBridge 更关注开源本地打印代理、远程任务轮询、原始打印指令（Raw Commands）、CLI 运维和可私有化集成。

如果业务系统已经生成好 PDF、图片、Office 文件或 ESC/POS、TSPL、ZPL、EPL、PCL 等设备指令，PrintBridge 会更像一个稳定、可审计、可改造的本机打印桥接层。

工作方式 ​

text
Web 页面 / 远程业务服务器
  |
  | WebSocket 下发任务，或 HTTP 轮询远程任务
  v
PrintBridge
  |
  | 校验来源、下载文件、转换格式、进入串行队列
  v
系统打印队列
  |
  v
打印机驱动与打印机

1. 下载并启动 PrintBridge ​

在 GitHub Releases 下载适合当前系统的安装包。

首次运行后，PrintBridge 会常驻在用户电脑上，并启动本机服务：

text
ws://127.0.0.1:17890/ws

同机 Web 页面通常连接 127.0.0.1。如果要从局域网其他设备连接这台电脑上的 Agent，需要使用这台电脑的局域网 IP，并配置 IP 白名单。

2. 选择默认打印机和纸张 ​

在 PrintBridge 设置界面完成：

  1. 选择默认打印机。
  2. 选择或填写默认纸张。
  3. 确认本机服务端口，默认是 17890。

打印任务也可以单独指定 printerName 和 paper。如果任务未指定，Agent 会使用默认配置。

3. 添加业务系统 Origin ​

把业务系统的 Origin 加入网站白名单，例如：

text
https://erp.example.com
http://localhost:5173

Origin 必须精确匹配浏览器 WebSocket 握手中携带的来源，包括协议、域名和端口。

4. 安装 SDK ​

bash
pnpm add print-bridge-sdk

也可以使用 npm 或 yarn：

bash
npm install print-bridge-sdk
bash
yarn add print-bridge-sdk

5. 发送第一单打印 ​

ts
import { PrintBridgeClient } from 'print-bridge-sdk';

const client = new PrintBridgeClient({
  ip: '127.0.0.1',
  port: 17890,
});

await client.connect();

await client.print({
  type: 'pdf',
  printerName: 'Label Printer',
  fileUrl: 'https://example.com/label.pdf',
  copies: 1,
  paper: {
    widthMm: 60,
    heightMm: 40,
  },
});

print() 返回 queued 只表示本机 Agent 已接收任务。后续下载、转换、打印和失败状态需要通过事件监听。

下一步 ​