Python调用win32print实现Windows静默打印

Windows 静默打印核心架构与 Python win32print 集成全景

一、Windows 打印子系统与 win32print 模块认知

在 Windows 架构中，所有外接打印设备与虚拟打印机均由系统核心服务 Print Spooler（打印后台处理程序，即 spoolsv.exe）统一调度。上层应用程序若要实现打印，通常有两条技术路径：其一是通过 GDI（图形设备接口）或 XPS 驱动管道，由系统绘制页面并弹出打印设置对话框；其二则是直接调用 Win32 原生 Spooler API（winspool.drv），直接向打印队列提交打印作业。

win32print 模块是 pywin32 对底层 winspool.drv 动态链接库的直接封装。它暴露了操作打印机句柄、启停文档流、枚举系统端口以及查询作业状态的核心接口。理解 win32print 的第一准则是：它本身并不负责版面排版或文档解析，它的职责是构建打印作业生命周期并将字节流推送到打印队列。

1. 环境准备与模块安装

在 Windows 系统的 Python 环境中安装 pywin32：

pip install pywin32

安装完成后，标准库环境即可导入 win32print。若在某些精简系统或打包环境提示找不到 DLL，通常是因为未执行 pywin32_postinstall.py -install 注册系统环境。

2. 打印机枚举与目标定位

实现静默打印的第一步是准确定位目标打印机。常见的业务诉求包括：获取系统默认打印机，或者从所有已连接设备中筛选出指定名称的设备（如条码机、小票机）。

import win32print

def list_printers():
    """枚举系统中所有本地和网络连接的打印机"""
    # PRINTER_ENUM_LOCAL (2) 枚举本地打印机; PRINTER_ENUM_CONNECTIONS (4) 枚举网络打印机
    flags = win32print.PRINTER_ENUM_LOCAL | win32print.PRINTER_ENUM_CONNECTIONS
    printers = win32print.EnumPrinters(flags)
    
    printer_list = []
    for flag, desc, name, comment in printers:
        printer_list.append(name)
        print(f"发现可用打印机: {name} (描述: {desc})")
    return printer_list

def get_target_printer(target_name=None):
    """获取目标打印机名称，若未指定则返回系统默认打印机"""
    if target_name:
        available = list_printers()
        if target_name not in available:
            raise ValueError(f"指定的打印机 [{target_name}] 不存在，请检查系统打印机列表。")
        return target_name
    
    default_printer = win32print.GetDefaultPrinter()
    print(f"当前系统默认打印机: {default_printer}")
    return default_printer

二、RAW 模式静默打印：小票与条码标签的核心实现

在物流快递、零售收银、工控流水线等场景中，普遍使用的是热敏小票打印机（遵循 ESC/POS 协议）或条形码/电子面单打印机（遵循 ZPL、TSPL 或 CPCL 协议）。这些设备拥有内置的字库芯片与微控制器，可以直接解析特定格式的纯文本指令。

对于此类硬件，最完美的静默打印方案即采用 win32print 的 RAW 模式。在该模式下，Windows Spooler 不会介入光栅化重绘，而是将构造好的指令字节流直接通过端口（USB、网口虚拟端口等）投递到打印机硬件，具备毫秒级启动、零内存膨胀、条码矢量边缘极其清晰等优势。

图 1：win32print RAW 打印核心调用链路与资源生命周期

1. 完整的 API 调用生命周期闭环

向 Windows Spooler 发送一次完整的 RAW 打印作业，必须严格遵循以下六个步骤：

1. OpenPrinter：传入打印机名称，向系统请求打开设备，获得操作系统内核级打印机句柄（hPrinter）。
2. StartDocPrinter：传入句柄、文档级别（通常为 1）以及一个三元组 (pDocName, pOutputFile, pDatatype)。其中 pDatatype 必须明确显式设置为 "RAW"。此调用标志着一次新打印作业的建立，系统会分配一个唯一的 JobId。
3. StartPagePrinter：通知打印服务开启一个新物理页面的数据传输。
4. WritePrinter：向打印缓冲区灌入二进制数据（bytes 类型）。这一步可以分批次循环写入，也可以一次性写入全部指令。
5. EndPagePrinter 与 EndDocPrinter：通知单页结束与整篇文档封包完成。此时 Spooler 将作业正式转为就绪状态并向物理端口推送。
6. ClosePrinter：关闭并释放打印机句柄。

2. 生产级 RAW 静默打印通用代码

以下是封装好的工业级 RAW 静默打印函数，包含严谨的异常处理与生命周期管理：

import win32print

def print_raw_bytes(printer_name: str, raw_data: bytes, doc_name: str = "SilentRawJob") -> int:
    """
    向指定打印机发送原始字节指令流（静默打印）
    :param printer_name: 打印机名称（系统识别名）
    :param raw_data: 二进制字节指令（如 ESC/POS 或 ZPL 字节）
    :param doc_name: 任务在 Windows 打印队列中显示的文档名称
    :return: 成功提交的 JobId (作业编号)
    """
    if not isinstance(raw_data, bytes):
        raise TypeError("raw_data 必须为 bytes 二进制流，文本请先 encode()")
        
    h_printer = None
    job_id = 0
    try:
        # 1. 申请底层打印机句柄
        h_printer = win32print.OpenPrinter(printer_name)
        
        # 2. 初始化作业元数据，指定数据格式为 RAW
        # 元组构成：(文档标题, 输出文件路径[通常为None], 数据类型)
        doc_info = (doc_name, None, "RAW")
        job_id = win32print.StartDocPrinter(h_printer, 1, doc_info)
        
        # 3. 开启页面并写入数据
        win32print.StartPagePrinter(h_printer)
        bytes_written = win32print.WritePrinter(h_printer, raw_data)
        
        # 4. 结束单页与整个文档
        win32print.EndPagePrinter(h_printer)
        win32print.EndDocPrinter(h_printer)
        
        print(f"作业已成功提交至队列 [{printer_name}], JobId: {job_id}, 写入字节数: {bytes_written}")
        return job_id

    except Exception as e:
        print(f"静默打印执行失败: {str(e)}")
        raise
    finally:
        # 5. 必须在 finally 块中释放内核句柄
        if h_printer is not None:
            win32print.ClosePrinter(h_printer)

3. 实战示例：小票切纸与电子面单打印

针对真实硬件，只需构造对应设备的规范字节流即可实现静默直印：

# 示例 1: ESC/POS 收银小票指令 (含中文、加粗与自动切刀)
def generate_receipt_data(store_name: str, order_no: str, amount: str) -> bytes:
    ESC = b"\x1b"
    GS = b"\x1d"
    
    buffer = bytearray()
    buffer += ESC + b"@"                  # 初始化打印机
    buffer += ESC + b"a\x01"              # 居中对齐
    buffer += ESC + b"!\x30"              # 倍高倍宽
    buffer += f"{store_name}\n".encode("gb18030")
    
    buffer += ESC + b"!\x00"              # 恢复标准字体
    buffer += ESC + b"a\x00"              # 左对齐
    buffer += f"订单编号: {order_no}\n".encode("gb18030")
    buffer += f"支付金额: ￥{amount}\n".encode("gb18030")
    buffer += b"--------------------------------\n"
    buffer += b"感谢光临，欢迎再次惠顾！\n\n\n"
    buffer += GS + b"V\x41\x00"            # 全切纸指令
    return bytes(buffer)

# 示例 2: ZPL 电子面单条码标签
def generate_zpl_label(package_id: str, destination: str) -> bytes:
    zpl = (
        "^XA\n"
        f"^FO50,50^A0N,36,36^FD目的地: {destination}^FS\n"
        "^FO50,110^BY3\n"
        "^BCN,100,Y,N,N\n"
        f"^FD{package_id}^FS\n"
        "^XZ"
    )
    return zpl.strip().encode("utf-8")

三、深层架构剖析：为什么普通文档不能直接 RAW 打印？

在实际开发中，经常有开发者尝试读取 example.pdf 或 contract.docx 的二进制数据，直接调用 win32print.WritePrinter 发送给普通的激光或喷墨打印机，结果往往是打印机吐出几十张空白纸，或者打印出成百上千行混乱的 ASCII 乱码代码。

图 2：Windows 打印子系统下的数据通路与处理机制对比

出现该现象的根本原因在于数据消费端（打印机硬件）的处理能力不同：

• RAW 直通通道：打印机固件拥有内建的指令解析器（如 ESC/POS 解码芯片或 ZPL 固件）。传入的字节流本身就是给芯片执行的程序。
• GDI / 版式驱动通道：普通的桌面办公打印机（惠普、佳能、爱普生等消费级设备）本质上是“哑设备”（GDI Host-Based Printer），它们不具备直接解析 PDF 树状对象、矢量曲线或嵌入字体的能力。它们依赖安装在 Windows 上的驱动程序，将复杂的文档页面逐页栅格化为极其庞大的点阵位图（如 EMF、XPS 流），再以厂商私有格式灌入打印头。

四、复杂文档（PDF与图像）的静默打印解决方案

如果业务目标是静默打印 PDF 报表、发票、合同或图像，则不能单纯依赖 win32print.WritePrinter 的 RAW 写入，而应结合 Windows 渲染管线。在工程实践中有两种高效且成熟的标准解决方案。

方案 A：通过 win32ui 调用 GDI 设备上下文（纯代码方案）

通过 win32ui.CreateDC() 创建打印机设备上下文（Device Context, DC），在系统底层建立一个与目标打印机物理 DPI、纸张边界相绑定的画布。然后借助 Python 图像处理库（如 Pillow 或 PyMuPDF）将文档光栅化后，通过 GDI 的 BitBlt 绘制到打印机 DC 上。

import win32ui
import win32print
from PIL import Image, ImageWin

def print_image_silent(printer_name: str, image_path: str, job_name: str = "ImagePrint"):
    """通过 GDI 设备上下文实现位图图像的高清静默打印"""
    img = Image.open(image_path)
    
    # 创建打印机设备上下文 DC
    h_dc = win32ui.CreateDC()
    h_dc.CreatePrinterDC(printer_name)
    
    # 开启打印作业与单页
    h_dc.StartDoc(job_name)
    h_dc.StartPage()
    
    # 获取打印机物理分辨率与可打印区域 (像素)
    # HORZRES (8) 宽度像素; VERTRES (10) 高度像素
    printer_w = h_dc.GetDeviceCaps(8)
    printer_h = h_dc.GetDeviceCaps(10)
    
    # 按等比例缩放适配页面
    img_w, img_h = img.size
    ratio = min(printer_w / img_w, printer_h / img_h)
    target_w, target_h = int(img_w * ratio), int(img_h * ratio)
    
    # 居中坐标计算
    x = (printer_w - target_w) // 2
    y = (printer_h - target_h) // 2
    
    # 利用 ImageWin 将 Pillow 位图绘制入 GDI DC
    dib = ImageWin.Dib(img)
    dib.draw(h_dc.GetHandleOutput(), (x, y, x + target_w, y + target_h))
    
    # 提交打印并销毁上下文
    h_dc.EndPage()
    h_dc.EndDoc()
    h_dc.DeleteDC()
    print("图像已成功通过 GDI 渲染管线提交打印。")

方案 B：win32print 设备就绪校验 + 无头组件执行（生产首选推荐）

对于包含多页复杂排版、矢量字体和公式的 PDF 文档，使用成熟的无头渲染组件执行静默打印是最健壮的工程选择。在实际架构中，利用 win32print 进行打印前的设备连通性与队列健康检测，确认无异常后，调用轻量开源工具（如 SumatraPDF）的静默命令行直接输出。

import subprocess
import win32print

def print_pdf_silent(printer_name: str, pdf_path: str, sumatra_cli_path: str = "SumatraPDF.exe"):
    """
    工业级 PDF 静默打印架构：
    1. 前置：win32print 校验打印机有效性
    2. 中置：调用轻量无头内核执行无弹窗物理光栅化打印
    """
    # 1. 严格校验目标打印机在系统中的可用性
    available = [p[2] for p in win32print.EnumPrinters(win32print.PRINTER_ENUM_LOCAL | win32print.PRINTER_ENUM_CONNECTIONS)]
    if printer_name not in available:
        raise RuntimeError(f"目标打印机 [{printer_name}] 未在 Windows 注册或已断开！")
        
    # 2. 调用 SumatraPDF 命令行实现彻底无弹窗静默打印
    # -silent: 零交互窗口
    # -print-to : 指定输出设备
    cmd = [
        sumatra_cli_path,
        "-silent",
        "-print-to", printer_name,
        pdf_path
    ]
    
    result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    if result.returncode != 0:
        raise RuntimeError(f"打印命令执行失败: {result.stderr.decode('gbk', errors='ignore')}")
        
    print(f"PDF 文档 [{pdf_path}] 已成功静默分发至 [{printer_name}]。")

五、生产环境健壮性：打印机状态监控与作业追踪

静默打印绝不代表“盲目投递”。在自动化服务、无人值守终端中，必须建立针对打印机硬件状态（缺纸、卡纸、脱机）以及已提交作业（Job）生命周期的轮询与反馈机制。

图 3：打印作业状态生命周期与异常监控状态机

1. 状态位掩码判定原理

调用 win32print.GetPrinter(hPrinter, 2) 返回的字典中包含 Status 字段；调用 win32print.EnumJobs(hPrinter, 0, -1, 2) 返回的每个作业字典中同样包含 Status 状态位。这些状态均为二进制位掩码（Bitmask），必须通过按位与运算（&）进行判定。

2. 作业监控轮询器实现

以下代码演示如何在提交作业后，持续跟踪该 JobId 的状态变化，直至其正常出纸或捕获异常超时：

import time
import win32print

def wait_job_completed(printer_name: str, target_job_id: int, timeout_sec: int = 30) -> bool:
    """
    轮询打印队列，追踪指定 JobId 的执行情况直至完成或超时
    """
    h_printer = win32print.OpenPrinter(printer_name)
    start_time = time.time()
    
    try:
        while True:
            # 枚举当前队列中的所有作业 (Level 2 提供完整状态信息)
            jobs = win32print.EnumJobs(h_printer, 0, -1, 2)
            matched_job = None
            
            for job in jobs:
                if job["JobId"] == target_job_id:
                    matched_job = job
                    break
            
            # 当作业从队列中消失，且之前无严重错误，通常代表硬件已完整接收并打印完成
            if matched_job is None:
                print(f"作业 [{target_job_id}] 已离开队列，打印交付完成。")
                return True
                
            status = matched_job["Status"]
            # 捕获异常位
            if status & win32print.JOB_STATUS_ERROR:
                raise RuntimeError(f"作业 [{target_job_id}] 触发错误状态 (JOB_STATUS_ERROR)")
            if status & win32print.JOB_STATUS_OFFLINE:
                print(f"警告: 打印机处于脱机状态，作业挂起...")
            if status & win32print.JOB_STATUS_PAPEROUT:
                print(f"警告: 打印机缺纸，等待补纸...")
                
            if time.time() - start_time > timeout_sec:
                raise TimeoutError(f"作业 [{target_job_id}] 在 {timeout_sec} 秒内未完成，当前状态值: {status}")
                
            time.sleep(1.0)
    finally:
        win32print.ClosePrinter(h_printer)

六、业务场景技术选型全景指南

不同业务对响应速度、版面保真度及开发成本的要求截然不同。为帮助读者在实际技术决策中少走弯路，下图给出了针对各类业务形态的最佳路径决策树：

图 4：Windows 环境下静默打印业务场景技术选型决策图

七、常见排查与避坑指南

在实际项目落地与服务器部署过程中，以下三个核心陷阱最为高发，需引起高度重视：

1. 汉字乱码与字库缺失（编码陷阱）

在使用 RAW 模式向小票机发送中文字符串时，若直接使用 text.encode('utf-8')，打印出的小票往往会出现大片乱码或生僻字。这是因为绝大多数中国市场流通的热敏小票机，其固件硬件字库内置的是 GBK 或 GB18030 编码表。在构造字节流时，必须使用 text.encode('gb18030')，以确保汉字区位码与打印机内建字模一一对应。

2. Windows 后台服务与计划任务中的权限隔离（Session 0 隔离）

当 Python 脚本作为 Windows 服务（如使用 NSSM 安装）或在系统任务计划程序（以 SYSTEM 用户运行）下启动时，程序运行在 Session 0 会话层。

• 现象：在当前用户桌面上测试静默打印完全正常，但转为 Windows 服务后报错找不到打印机，或者作业卡在队列无法输出。
• 原因：网络共享打印机（如 \\\\PrintServer\\HP_Laser）是基于登录用户的漫游凭据映射的，SYSTEM 账户没有网络打印机凭据；同时 Session 0 默认被禁止访问图形设备与用户空间资源。
• 解决方案：在服务管理控制台中，将该 Windows 服务的启动身份从“本地系统账户 (LocalSystem)”修改为具备打印机访问权限的具体域账户或管理员账户；或者在系统层建立本地虚拟端口（Standard TCP/IP Port，直接指定打印机 IP），将其安装为真正的“本地打印机”。

3. 高并发场景下的 Spooler 锁死与任务丢单

在电商大促打单或多线程批处理场景中，若多个 Python 线程同时高频调用 win32print.OpenPrinter 并行灌入数据，由于打印机物理端口是排他性的单工通道，极易造成 Windows Spooler 死锁或端口超时。

• 最佳工程实践：在 Python 业务层引入生产者-消费者模型（如 queue.Queue 或 Redis 队列），由单个工作线程独占打印机句柄，对打印任务进行串行化消费与交付；严格保障一次任务全闭环后才开启下一个任务，从根本上杜绝并发竞态冲突。

八、总结与技术准则

Python 调用 win32print 实现 Windows 静默打印是一套兼具高性能与高灵活性的技术体系：

• 指令类打印（小票、标签）：坚决采用 win32print 的 RAW 模式，通过 OpenPrinter -> StartDocPrinter -> WritePrinter 建立无感知管道，响应迅速且不占系统资源。
• 版式类打印（PDF、Office）：坚决避免盲目投递 RAW 字节流，理清设备能否硬件解码；优先采用“win32print 健康巡查 + 无头轻量组件光栅化”或“win32ui GDI 设备上下文绘图”方案。
• 工程化交付底线：所有系统底层对象必须由 try...finally 兜底闭合；针对生产关键链路，必须结合 EnumJobs 状态位轮询建立闭环反馈机制。