简介这是一套基于C#开发的小票打印源码项目面向需要在零售、餐饮、超市等业务场景中实现收据、结算单输出的.NET开发者。压缩包内共27个文件主要包含cs源码、sln解决方案、resx资源文件同时附带exe可执行程序、pdb调试符号和dll库可帮助读者直接查看工程结构、运行体验或进行二次调试。资源整体约73KB轻量易部署适合快速学习。目前已有215人学习。源码围绕PrintDocument类展开覆盖初始化打印对象、设置页面属性、在PrintPage事件中用Graphics绘制文本与商品明细并通过PrintDialog调用系统打印对话框等核心流程Form2与TicketSet等模块展示了界面与打印逻辑的分离设计Properties与Resources目录则有助于理解.NET工程的配置与资源管理方式。对于希望掌握C#打印机通信、自定义小票版式的初学者这是一份可以直接运行的示例工程。1. 项目概述小票打印系统到底在做什么小票打印这个需求平时看着不起眼真动手做的时候才发现水挺深。这几年我帮朋友和客户陆陆续续做过几套小票打印的完整源码方案从最早的串口热敏打印机到后来带蓝牙的便携式小票机再到对接外卖平台自动出单的云打印踩了不少坑也沉淀出一套可以直接拿来改的代码结构。这篇就基于“小票打印 源码”这个项目把我自己实际搭过、跑过、稳定运行过的方案拆开讲一遍。先明确一下这东西是什么所谓小票打印源码就是用代码控制一台热敏打印机按照业务需求输出定长或不定长的纸质小票。它解决的典型问题包括收银台结账后快速出单、后厨订单自动拆分打印、外卖平台订单自动接单出票、商品价签批量打印、排队叫号小票以及各类会员充值凭证的打印。适合参考这套源码的人主要是有收银系统、餐饮管理软件、便利店管理工具、仓管系统开发需求的后端或全栈开发者也可能是想自己折腾一套家用小票机方案的技术爱好者。我在实践中最常用的一套组合是“Python后端 ESC/POS指令 网口/USB热敏打印机”同时辅以Node.js做局域网打印服务、小程序蓝牙打印等分支方案。相比那些直接调SDK的做法自己掌控指令层和模板层最大的好处是可移植性强换打印机品牌只需要改指令兼容层业务层完全不用动。这篇会把这套方案的架构、核心代码、踩坑记录全部摊开照着做基本能把一套小票打印服务跑起来。2. 核心原理从业务数据到纸上文字的完整链路2.1 打印数据流与整体架构小票打印的完整数据链路可以拆成五个环节业务系统产生订单数据、模板引擎将订单渲染为打印内容、打印服务把内容编码为字节流、通信通道把字节流送到打印机、打印机执行指令完成出纸。任何一个环节出问题最终表现都是“打印不正常”但根因可能差别很大。我一开始做的时候犯过一个典型错误把打印内容直接当文本发给打印机结果打印机吐出来一堆乱码和奇怪符号。原因很简单热敏打印机不吃纯文本它吃的是指令流。你需要告诉它初始化、对齐方式、字体大小、走纸距离、切刀动作这些全靠ESC/POS指令控制。所以架构里必须有一层“指令封装层”把业务数据翻译成打印机听得懂的字节序列。实际源码里我分了四层层与层之间用接口隔开后续换打印机驱动只改最底层。代码结构大致是这样printer_service/ ├── core/ # 核心指令封装 │ ├── escpos.py # ESC/POS指令集 │ ├── protocol.py # 通信协议USB/串口/网口 │ └── codec.py # 文本编码处理 ├── template/ # 小票模板渲染 │ ├── renderer.py # 模板引擎 │ └── layouts/ # 不同场景的小票布局 ├── api/ # 对外服务接口 │ ├── http_api.py # HTTP调用入口 │ └── websocket.py # 长连接推送入口 └── utils/ # 日志、配置、重试机制这四层各有分工core层负责把“打印一行文字”这种操作编码成字节流template层负责把“订单数据”变成“打印内容”api层负责接收外部调用utils层处理网络异常、打印任务重试等杂事。分层的意义在于如果某天要把58mm打印机换成80mm的或者从USB连接换成网口连接只需要改core层和template层的部分参数api层和业务方完全无感。2.2 ESC/POS指令集控制打印机的“通用语言”ESC/POS是这个领域的实际标准由爱普生提出目前几乎所有热敏打印机都支持。它的核心逻辑就是“转义字符功能码”。ESC是ASCII码里0x1B这个字符POS是“打印机操作系统的缩写指令通常以ESC开头后面跟功能码和参数。我用得最多的几条指令列出来这些是任何小票打印源码都绕不开的基础功能指令说明初始化打印机ESC (0x1B 0x40)清除缓冲区、恢复默认设置每次打印前必发打印并换行LF (0x0A)将当前行内容输出并走纸一行设置对齐方式ESC a nn0左对齐n1居中n2右对齐设置字体大小GS ! nn的位组合控制倍宽倍高打印条码GS k m d...m选择条码类型后跟数据和结束符切纸GS V mm1部分切m66全切打开钱箱ESC p m t通过打印机驱动钱箱打开比如初始化后居中打印一行标题对应的字节序列就是ESC b\x1b init ESC b center ESC ba b\x01 text 欢迎光临.encode(gbk) line_feed b\n payload init center text line_feed注意这里文本编码用了GBK。大多数国内热敏打印机出厂默认中文字库是GBK/GB2312如果你用UTF-8直接编码打印机识别不了出来的就是乱码。这个细节我见过太多人栽跟头后面专门用一节讲编码问题。2.3 编码问题乱码的根源与解决方案小票打印机的中文编码处理是整套源码里最容易出问题的环节没有之一。国内主流的58mm和80mm热敏打印机内置字库基本是GBK编码但业务系统内部通常用UTF-8存储数据。两边编码不一致中间又没有做转换结果就是中文全部变成问号或者乱码。我的做法是在codec.py里统一处理取出业务数据时先把所有字符串强制转成UTF-8内部表示然后在编码发送给打印机时统一用GBK编码。非中文内容比如数字、英文、符号则完全不受影响。def encode_text(text: str) - bytes: try: return text.encode(gbk) except UnicodeEncodeError: # 个别字符GBK无法编码时降级为UTF-8 return text.encode(utf-8)这里有个小坑GBK编码的汉字每个占2字节但ASCII字符只占1字节。设计小票模板时计算一行能放多少个字需要按字节算不能按字符数算。比如58mm打印机一行最多32个英文字符或16个汉字因为打印机的点数是固定的576点每个ASCII字符占12点宽每个汉字占24点宽。不搞清楚这个换算关系模板对齐永远是歪的我后面有一节专门讲模板对齐的实操方法。3. 模块设计与源码落地把方案变成能跑的代码3.1 打印任务队列与状态机实际生产环境里小票打印不是来一单打一单这么简单。用户可能同时下单后厨可能同时有多张票要出网口打印机也可能因为过热卡住。如果直接并发调打印接口很容易出现指令交错、内容串单的事故。所以我在源码里加了一个打印任务队列把所有打印请求串行化处理。队列的设计参考了状态机思路每个任务有5个状态pending(等待)、processing(打印中)、success(成功)、retry(待重试)、failed(失败)。任务先进入pending队列由调度器统一取出执行成功后标记success如果打印机返回异常任务进入retry队列最多重试3次超过3次标记failed并告警。class PrintTask: def __init__(self, task_id, device_id, payload): self.task_id task_id self.device_id device_id self.payload payload self.status pending self.retry_count 0 self.max_retry 3调度器每秒扫描一次队列取出pending状态的任务执行retry状态的任务按指数退避策略延迟重试第一次重试延迟2秒第二次4秒第三次8秒。这个策略避免了打印机刚恢复时被一拥而上的任务再次打挂。任务失败的告警怎么做呢最简单有效的方式是飞书或钉钉的webhook机器人。打印机连续失败超过5次服务自动推送一条告警消息到运维群内容包括设备ID、最近一条失败任务ID、失败原因。我在实际项目中靠这个功能在夜里抢修过好几次打印机卡纸故障。3.2 Python示例USB热敏打印机实现先看最常见的一种场景打印机通过USB线直接连在一台Windows收银机上Python服务跑在同一台机器上通过USB口发送打印数据。这种场景适合单店收银部署最简单。Python操作USB打印机有两个方案可选。一是用python-escpos库它封装了USB、串口、网口三种通信方式API很友好二是直接用pyusb更底层、可控性更强。我的经验是先用python-escpos快速跑通流程等深入了解指令后再自己封装这样学习曲线比较平缓。from escpos.printer import Usb # USB VendorID和ProductID需要根据打印机型号查询 # 常见热敏打印机为 0x0416:0x5011 printer Usb(0x0416, 0x5011, timeout0, in_ep0x81, out_ep0x03) printer.set(aligncenter, height2, width2) printer.text(我的小卖部\n) printer.set(alignleft, height1, width1) printer.text(单号: 20250101001\n) printer.text(--------------------------------\n) printer.text(可乐 x1 3.00\n) printer.text(薯片 x2 12.00\n) printer.text(--------------------------------\n) printer.set(alignright) printer.text(合计: 15.00元\n) printer.cut()这段代码有几个关键点。set方法的align参数控制对齐height和width控制倍宽倍高cut方法执行切刀动作。打印商品行时商品名、数量、金额的间隔我用了手工空格拼接这种写法在商品名长度不固定的场景下很容易对不齐。更好的做法是计算好列宽用格式化字符串对齐这部分我在模板对齐的章节展开。3.3 Node.js示例局域网与云端打印服务单店场景用USB没问题但如果门店有多台收银机或者需要中心化控制多台打印机就得走网络打印方案。网络打印分两种一种是打印机本身带网口直接通过TCP/IP访问9100端口发送数据另一种是打印机通过USB连到一台电脑电脑上跑一个代理服务把网络请求转换成USB数据发给打印机。我倾向于推荐第一种打印机直接插网线IP固定减少中间节点稳定性最好。Node.js实现网口打印非常简单因为9100端口就是一个裸TCP端口不需要任何握手协议连上之后直接写字节流就行。const net require(net); function printToNetworkPrinter(ip, port, payload) { return new Promise((resolve, reject) { const socket net.createConnection(port || 9100, ip, () { socket.write(payload); }); socket.on(data, () { socket.destroy(); resolve(); }); socket.on(error, (err) { socket.destroy(); reject(err); }); // 设置超时避免打印机离线导致连接挂死 socket.setTimeout(3000); socket.on(timeout, () { socket.destroy(); reject(new Error(print timeout)); }); }); }payload的构造就是前面ESC/POS指令的字节序列。我通常把指令封装函数放在单独模块里比如居中标题用makeCenterTitle(text)商品行用makeProductRow(name, qty, amount)。这样业务代码里只需要组装数据不直接跟字节打交道代码可读性好很多而且换打印机型号时只需要调整封装函数内部实现。3.4 微信公众号/小程序蓝牙打印方案除了固定场景的收银台现在越来越多商家需要在移动场景打印小票比如上门取货、外卖配送、地推活动现场。这类场景的标配是“小程序/公众号页面 蓝牙便携打印机”。蓝牙打印的实现逻辑和小票机的指令是一样的只是通信通道从USB/网口换成了BLE。以微信小程序为例核心流程是调用wx.openBluetoothAdapter初始化蓝牙、wx.startBluetoothDevicesDiscovery扫描设备、匹配到目标打印机后wx.createBLEConnection建立连接、然后通过wx.writeBLECharacteristicValue写入数据。BLE一次写入的数据长度有限制一般在20字节左右所以长数据必须分包发送还要在每包之间加延时否则打印机缓冲区溢出会丢数据。蓝牙写数据的封装大概是这样的function writeBLEData(deviceId, serviceId, charId, data) { const CHUNK_SIZE 18; // 留2字节给协议头实际可用18字节 const chunks []; for (let i 0; i data.length; i CHUNK_SIZE) { chunks.push(data.subarray(i, i CHUNK_SIZE)); } let index 0; return new Promise((resolve, reject) { function writeNext() { if (index chunks.length) { resolve(); return; } wx.writeBLECharacteristicValue({ deviceId, serviceId, characteristicId: charId, value: chunks[index], success: () { index; setTimeout(writeNext, 20); // 20ms延时防止数据丢包 }, fail: reject }); } writeNext(); }); }蓝牙打印遇到的最典型问题是“能连上但打不出字”或者“打一半断了”。通常连上但打不出字是因为没有先发送ESC 初始化指令打一半断了大概率是分包间隔太短导致数据丢失。微信的BLE接口在安卓和iOS上的表现还不一样安卓需要打开系统定位权限才能扫描到蓝牙设备iOS在每次连接前最好重新发起扫描。这些细节在我最开始做的时候完全不知道都是拿着真机一台一台试出来的。4. 模板设计与常见问题排查4.1 小票排版与模板对齐计算小票美观度直接影响顾客体验这一点常被忽略。一张对不齐、乱换行的小票顾客会下意识觉得这家店不专业。所以小票模板设计是源码之外的重要一环而这一环的核心就是字符宽度计算。58mm热敏打印机的物理宽度是384点但有效打印宽度通常只有360点左右。不同字体模式下每个字符占用的点数不一样ASCII字符默认占12点汉字占24点倍宽模式下分别占24点和48点。所以一行最多能容纳的字符数是这么算的360除以12等于30个ASCII字符360除以24等于15个汉字。我封装了一个自动等宽拆分函数用来处理商品名过长时的换行逻辑def split_line(text, max_bytes, fontnormal): lines [] current current_bytes 0 for char in text: char_bytes 2 if ord(char) 255 else 1 if char_bytes 2: char_width 24 else: char_width 12 if font normal else 24 if current_bytes char_width max_bytes: lines.append(current) current char current_bytes char_width else: current char current_bytes char_width if current: lines.append(current) return lines有了这个函数商品名再长也不会撑破模板边框而是自动截断到多行显示。实际上更精细的做法是把商品名按最大宽度截断超出的部分用省略号或换到第二行数量列和金额列永远固定在右边。我习惯用中文字符宽度为2、ASCII宽度为1的“半角等效宽度”来做对齐计算然后配合全角空格填充比直接数空格稳得多。4.2 常见问题速查乱码、不走纸、重复打印做小票打印源码开发最耗时的不是写功能而是排查现场问题。我把这几年遇到概率最高的几个问题整理成了一张速查表方便遇到问题时直接对号入座现象可能原因排查方法中文乱码编码用了UTF-8打印机只认GBK发送前统一转GBK编码打印空白打印机热敏头脏了或老化用热敏纸擦拭打印头更换热敏纸测试不出纸纸张装反、卡纸、打印机离线检查纸张方向和打印机状态灯打印内容重叠缺少LF换行指令每行内容后必须加LF重复打印同一订单业务层没有幂等控制打印任务加唯一ID成功后就地标记单号不连续打印机丢任务任务队列加事务失败任务重入队小票两侧裁切不均纸张宽度和打印机不匹配确认打印纸宽度是58mm还是80mm蓝牙打一半断分包间隔太短每包发送后等待至少20ms这里特别说一下重复打印的问题。刚开始做的时候我把打印逻辑直接放在下单接口里面用户下单后执行后端代码直接打印。一旦打印机异常后端异常被捕获后重试结果订单正常但小票打了两张。后来我改成任务队列加幂等控制每个订单生成一个唯一的printTaskId打印成功后写入Redis记录重试时先查记录已经成功就不再打印。这个机制在联调时帮了大忙也避免了不少客诉。4.3 日志与监控线上排查问题的基础设施没有日志支撑的小票打印系统出了问题等于盲人摸象。我一开始写打印服务时日志只有一句print等到现场问题抛出来完全无从下手。后来我老老实实分了三类日志请求日志、打印任务日志、设备日志。请求日志记录谁在什么时间请求了打印服务请求的参数是什么打印任务日志记录每个任务的完整生命周期包括入队时间、开始时间、完成时间、重试次数和错误信息设备日志记录每台打印机的状态包括在线离线变化、累计打印张数、最近一次成功打印时间。这些日志统一写到按天切割的文件里同时输出到标准输出便于容器收集。日志里最该关注的是打印耗时数据。同一个任务正常情况应该在1秒内完成如果连续多次超过3秒大概率是打印机通信出现了问题积压的任务会越来越多。我在监控里加了一个简单的阈值报警最近5个打印任务平均耗时超过2秒就推送一条警告消息。这个指标比任何花哨的监控都管用。5. 扩展方向与完整源码生态的思考小票打印这个项目从最基础的“驱动一台打印机”往上扩展可以做很多事。我自己实践过两个方向一个是把打印服务封装成HTTP API部署到内网或者云服务器上让前端页面、收银App、进销存系统统一通过接口调用真正做到一套服务多处复用另一个是对接业务系统的消息队列比如订单系统把下单消息推送到Kafka打印服务订阅消息后自动出单彻底实现“订单来了小票自动打”这也正是很多外卖平台商家在用的模式。我目前更推荐的做法是先做HTTP API版本没有引入消息队列之前系统的复杂度会低很多。核心接口就两个一个用于提交打印任务一个用于查询任务状态。任务提交接口接收JSON格式的订单数据返回taskId查询接口根据taskId返回状态。业务方只需要调这两个接口不用关心打印机具体是哪款、通信是USB还是网口也不关心模板长什么样实现了比较干净的关注点分离。至于“源码生态”这个词我更愿意把它理解成一个不断积累的个人代码库。做小票打印的过程里我沉淀的不只是那一个项目的源码还有指令封装库、模板渲染器、任务队列框架、各种型号打印机的适配参数。下一个项目来了复制一份直接改改工作量可能只有原来的30%。我建议在做这类偏底层设备的源码项目时刻意划分出“能复用的公共模块”和“为当前项目定制的业务模块”这两部分长期积累下来的公共模块就是自己最宝贵的技术资产。最后再分享一点我在多个项目里验证过的经验小票打印系统的难点从来不在打印机本身而在于边界条件。比如断电恢复后任务怎么处理、连续打印几百张后打印机过热怎么办、多台打印机同时打印时怎么调度、模板在内容超过一屏时怎么自动分页。把这些边界场景都想到了系统才真正达到可上线状态。如果只写一个“传入文本打印文本”的demo那整个过程其实三小时就能完成但也仅仅是个demo而已。真正有用的源码应该是把未来可能出问题的每一个角落都提前想到并且用一个可靠的结构兜住。本文还有配套的精品资源点击获取