winget install --id=Vergil.PrintBridge -e A local print bridge for web applications.
PrintBridge 是一个运行在用户电脑上的本地打印代理程序。它让受信任的 Web 页面或远程业务服务器，把 PDF、图片、Office 文件和原始打印指令发送到本机打印队列，用于标签、面单、小票、报表等需要稳定静默打印的业务场景。
它不替代打印机驱动，也不绕过系统打印队列。PrintBridge 负责接收任务、校验来源、下载或转换文件，并把任务提交给本机操作系统；真正的出纸仍由系统打印队列、打印机驱动和打印机完成。
https://example.comhtml 使用 URL，raw-html 使用内联 HTML 文本print-bridge-sdk：npm install print-bridge-sdk
连接本机 Agent 并发送第一个 PDF 打印任务：
import { PrintBridgeClient } from "print-bridge-sdk";
const client = new PrintBridgeClient();
client.on("status", (event) => {
console.log(event.jobId, event.status, event.message);
});
await client.connect();
const accepted = await client.print({
type: "pdf",
fileUrl: "https://example.com/label.pdf",
});
console.log(accepted.jobId, accepted.status);
print() 返回 queued 只表示任务已经进入 PrintBridge 队列。下载、转换和提交系统打印队列等后续结果通过 status 事件返回。完整用法见 JSSDK 文档。
查看更多截图
PrintBridge 不是传统意义上的 Web 打印控件。C-Lodop / Lodop 更擅长打印设计、套打、表格、条码和页面内容打印；PrintBridge 更关注开源本地打印代理、远程任务轮询、原始打印指令（Raw Commands）、CLI 运维和可私有化集成。
如果业务系统已经生成好 PDF、图片、Office 文件或 ESC/POS、TSPL、ZPL、EPL、PCL 等设备指令，PrintBridge 会更像一个稳定、可审计、可改造的本机打印桥接层。
PrintBridge 可以作为工位、门店或仓库终端上的本地代理，定时从业务服务器拉取打印任务，并把执行状态回报给服务器。
这适合“系统产生任务，指定终端自动打印”的场景，例如生产标签、仓库面单、拣货单、收银小票等。
PrintBridge 支持原始打印指令（Raw Commands）。业务系统可以自己生成 ESC/POS、TSPL、ZPL、EPL、PCL、PostScript 等设备指令，PrintBridge 只负责把 bytes 原样提交到系统打印队列。
这适合标签机、小票机和工业打印设备。PrintBridge 不解析这些设备语言，也不负责生成标签、小票或 RFID 指令。
PrintBridge 支持 DOCX、XLSX 和 PPTX 文件。Office 任务必须提供 HTTP(S) file_url；本机 Agent 下载文件并转换为 PDF 后，再进入打印流程。
Office 文件打印依赖本机安装的转换软件：
soffice 或 libreoffice。PrintBridge 不内置 Office 转换器。缺少对应软件、转换失败或转换超过 120 秒时，该 Office 打印任务会失败。Windows 发生转换超时时，只会清理该任务启动的 Office 实例，不会关闭用户已经打开的 Word、Excel 或 PowerPoint。
html 用于打印公开 URL 指向的 HTML 页面，必须提供 HTTP(S) file_url；raw-html 用于直接打印内联 HTML，必须提供非空 html，且不能提供 file_url。两种 HTML 任务都支持 wait_ms（0 到 30000 毫秒）、copies 和 paper：
{
"type": "print",
"job_id": "JOB-HTML-001",
"format": "html",
"file_url": "https://example.com/invoice/1",
"wait_ms": 1000,
"copies": 1,
"paper": { "width_mm": 210, "height_mm": 297 }
}
{
"type": "print",
"job_id": "JOB-RAW-HTML-001",
"format": "raw-html",
"html": "<h1>Invoice</h1>",
"wait_ms": 1000,
"copies": 1,
"paper": { "width_mm": 210, "height_mm": 297 }
}
浏览器端 JSSDK 使用 camelCase 的 fileUrl、waitMs，只负责序列化任务；本机 Agent 负责渲染 HTML 为 PDF，再进入打印流程。HTML 页面及其加载的资源只允许访问公开 HTTP/HTTPS 地址；本机、私网和 file: 资源会被拒绝。
HTML 渲染不内置浏览器，所有平台和运行模式都必须使用已安装的 Chromium 系浏览器；不提供原生 WebView fallback：
| 平台 | 浏览器渲染器 |
|---|---|
| Windows | Edge → Chrome → Chromium |
| macOS | Chrome → Chromium |
| Linux | Chrome → Chromium |
GUI 和 systemd 托管的 Linux headless 产品都遵循此要求；没有可用浏览器时，HTML 任务会以 renderer-unavailable（RendererUnavailable）失败。
在 Releases 下载最新版本。
| 产品 | 平台 | 架构 | 安装包 |
|---|---|---|---|
| Desktop | Windows | x86_64 | NSIS .exe、WiX .msi |
| Desktop | macOS | Intel、Apple Silicon | 对应架构的 macOS 安装包 |
| Desktop | Linux | x86_64、ARM64 | .deb、.rpm、.AppImage |
| Headless | Linux | x86_64、ARM64 | .deb、.rpm |
在 PowerShell 中运行以下命令，安装最新桌面版：
winget install --id Vergil.PrintBridge --exact
在 PowerShell 中运行以下命令，下载、校验并安装最新的 x64 版本：
irm https://printbridge.pages.dev/install.ps1 | iex
brew tap vergil-lai/tap
brew install --cask printbridge
APT（Debian/Ubuntu）
首次安装时添加 PrintBridge 软件源和签名公钥：
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL \
https://printbridge.pages.dev/apt/printbridge-archive-keyring.gpg \
| sudo tee /etc/apt/keyrings/printbridge.gpg >/dev/null
sudo tee /etc/apt/sources.list.d/printbridge.sources >/dev/null <<'EOF'
Types: deb
URIs: https://printbridge.pages.dev/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/printbridge.gpg
EOF
sudo apt update
安装桌面版：
sudo apt install print-bridge
无桌面环境请选择 Headless 服务端版本：
sudo apt install print-bridge-server
仓库签名公钥指纹为 7D9F6986BAD473CE95B1FDA55B1B363C885CD16D。
RPM/DNF（Fedora/RHEL/Rocky Linux/AlmaLinux）
首次安装时添加 PrintBridge 软件源：
curl -fsSL https://printbridge.pages.dev/rpm/printbridge.repo \
| sudo tee /etc/yum.repos.d/printbridge.repo >/dev/null
sudo dnf makecache
安装桌面版：
sudo dnf install print-bridge
无桌面环境请选择 Headless 服务端版本：
sudo dnf install print-bridge-server
首次刷新仓库时，DNF 会要求确认导入 PrintBridge GPG 公钥。公钥指纹同样为 7D9F6986BAD473CE95B1FDA55B1B363C885CD16D。
更新方式
通过 Homebrew 安装时：
brew upgrade --cask printbridge
通过 APT 仓库安装时，先刷新软件包索引，再根据已安装的版本选择一条升级命令：
sudo apt update
# Desktop
sudo apt install --only-upgrade print-bridge
# Headless
sudo apt install --only-upgrade print-bridge-server
通过 RPM 仓库安装时：
sudo dnf upgrade --refresh
通过 Releases 安装的 Desktop 版本可使用设置页中的内置更新功能。PrintBridge 不提供单独的 print-bridge update 命令。
Desktop 和 Headless 都安装同名的 print-bridge 命令，但属于互斥产品，不能在同一台机器上同时安装。Linux Headless 适合无桌面的服务器、树莓派、工控机和专用打印主机；安装 deb/rpm 后会自动创建 printbridge 系统用户并启用 systemd system service。
Desktop 的“设置”页会显示命令行工具状态：macOS 可授权创建 /usr/local/bin/print-bridge；Windows 可把包含独立 console CLI 的安装目录加入当前用户 PATH，操作后需要重新打开终端；Linux deb/rpm 已自动提供 /usr/bin/print-bridge，因此不显示管理按钮；AppImage 可创建 ~/.local/bin/print-bridge 用户级链接，如果该目录不在 PATH 中，需由用户自行加入。
首次运行后，在 PrintBridge 设置界面完成：
https://example.com127.0.0.1；如需让局域网设备连接，再添加明确的 IP 或网段，例如 192.168.1.10、192.168.1.0/24Headless 没有设置界面，通过同一个 print-bridge CLI 完成配置和诊断。安装 deb/rpm 后先配置默认打印机、纸张、Origin 白名单和远程任务地址，再检查 systemd 服务状态：
print-bridge printer
print-bridge printer set-default "Printer Name"
print-bridge paper set 60 40
print-bridge origin add "https://example.com"
print-bridge remote set-url "https://example.com/print-task"
print-bridge remote enable
systemctl status print-bridge
Headless 的 print-bridge serve 由 systemd 自动启动，正常安装后无需手工运行，也没有 serve install/uninstall 命令。
PrintBridge 提供 print-bridge CLI，用于在不打开 GUI 的情况下完成基础运维和诊断：
print-bridge printer
print-bridge printer set-default "Printer Name"
print-bridge paper
print-bridge paper set 60 40
print-bridge origin add "https://example.com"
print-bridge ip add "192.168.1.0/24"
print-bridge remote enable
print-bridge remote set-url "https://example.com/print-task"
print-bridge remote generate-device-id
print-bridge task
print-bridge doctor
config export/import 支持加密配置迁移；导出时可用重复的 --only 选择字段。Desktop 额外支持 autostart 和 app language，Headless 固定使用英语并由 systemd 管理自启动。
GUI 安装包和 headless 安装包都提供同名的 print-bridge CLI，但不能同时安装。只有 Linux headless 包提供 print-bridge serve；安装 deb/rpm 后会自动创建 printbridge 系统用户并启用 systemd 服务，无需 serve install/uninstall。
项目采用 Cargo workspace：crates/core 保存纯模型，crates/runtime 保存队列和平台运行时，crates/cli 保存统一功能命令；apps/desktop 是 Vue + Tauri GUI，apps/server 是 Linux headless 产品。桌面功能通过本地 IPC 调用同一个 CommandService，网络只暴露 /ws。
CLI 直接读写与 GUI 相同的本机配置，并可查看本地任务历史。完整命令见 技术说明。
浏览器页面接入请使用 print-bridge-sdk。SDK 会连接本机代理 的 WebSocket 服务，并封装打印、批量打印、心跳和任务状态事件。
PrintBridge 也支持远程任务轮询模式：业务服务器维护待打印任务，本机代理定时拉取任务、提交到系统打印队列，并把 accepted、success、failed 状态上报回服务器。
Web 页面 / 远程业务服务器
|
| WebSocket 下发任务，或 HTTP 轮询远程任务
v
PrintBridge
|
| 校验来源、下载文件、转换格式、进入串行队列
v
系统打印队列
|
v
打印机驱动与打印机
WebSocket 里的 submitted，以及远程状态上报里的 success，表示任务已经成功提交到系统打印队列，不代表打印机已经完成出纸。
PrintBridge 运行在用户本机，能够访问本机打印机。部署时请至少做到：
127.0.0.1 不可删除具体协议、API、配置格式、开发命令和平台细节请看：
如果 PrintBridge 帮到了你，欢迎给项目一个 Star ⭐️。
如果你在使用中遇到问题或有改进建议，欢迎提交 Issue。
Windows 版本随包使用的 SumatraPDF 适用其自身许可证。详见 THIRD_PARTY_NOTICES.md。