简介一份基于C#与Windows Forms开发的斑马打印机PRN文件打印测试源码包面向需要调试斑马打印机指令的开发者与测试人员。其中围绕PRN指令解析、ZPL/EPL通信协议、GUI控件设计及System.IO文件操作等核心知识点展开完整展示了从加载PRN文件、选择打印机、预览打印效果到执行打印任务的全过程。压缩包共23个文件以cs源码文件为主辅以exe可执行程序、pdb调试符号、resources资源文件及sln工程文件等便于直接编译运行与断点调试整体约142KB结构紧凑适合作为二次开发基础。已有251人学习下载。借助该源码可快速掌握C#与Winform结合硬件设备交互的方法理解斑马打印机指令集的实际应用同时包含基本的调试与异常处理机制可辅助定位错误指令并可直接改造为自定义打印测试工具对相关项目开发具有较高的参考价值。1. 拿到一份斑马打印机 PRN 打印测试源码先把调试工具的地基打牢做打印集成的人大概率遇到过这种场景项目方甩过来一个 .prn 文件说这是客户那边的标签模板你打出来看看效果。你用记事本打开看到满屏^XA、^FO、^FS这种像乱码又不是乱码的东西一时不知道这文件到底能不能打、打出来长什么样。这份斑马打印机 PRN 文件打印测试源码就是一个基于 C# 和 Winform 的小工具核心干三件事加载 PRN 文件、连接到斑马打印机的网络端口、把原始字节发过去触发打印。适合三类人做标签打印集成的 C# 开发者、需要批量验证 PRN 指令正确性的技术支持、以及刚接触 ZPL 想找个现成发送器入门的初学者。它能帮你在不依赖第三方商业工具的前提下自己动手把发文件到打印机这条路彻底打通顺带理解打印机通信的底层逻辑。2. 读懂 PRN 文件与 ZPL 指令打印测试的第一步是看懂指令结构2.1 PRN 文件不是图片也不是文档而是一段打印指令文本很多第一次接触 PRN 文件的人会拿它当普通文本文件处理用记事本打开后复制内容、粘贴到聊天窗口、再另存为 .txt 发送结果打印机要么没反应要么吐出一张全是乱码的纸。这背后的关键点是PRN 文件对于斑马打印机来说本质上是一段可以直接被打印机解释执行的指令流而不是给人阅读的排版文档。斑马打印机目前主流解释两种指令语言ZPLZebra Programming Language和 EPLEltron Programming Language。老款 Eltron 机型偏向 EPL新机型基本都是 ZPL 主导。这份源码对应的测试对象主要是 ZPL 体系的 PRN 文件因为 ZPL 在标签尺寸控制、条码精度、中文支持上都更现代。PRN 文件的典型特征是以^XA开头、以^XZ结尾中间是一串以^开头的命令。^XA表示开始一个标签格式^XZ表示结束并触发打印。为什么这个认知对测试很重要因为你在 C# 里读取 PRN 文件时如果用了StreamReader按文本读、然后再编码输出文件里的命令会被原样保留没错但换行符、BOM、编码转换都可能产生偏差。比如 ZPL 命令之间用 CRLF 或者 LF 其实都能解释但如果你用 Unicode 编码重新写一遍文件文件头会多出 BOM 字节某些固件版本的打印机就会把这几个额外字节当成非法命令忽略掉造成标签前面缺一块这种诡异现象。所以我处理 PRN 文件时一律按二进制读取也就是后面代码里会讲的File.ReadAllBytes让原始字节流完整无损地到达打印机。2.2 一段典型 ZPL 指令逐行拆解字段位置、字体、条码与其空谈理解 PRN不如直接拆一段真实项目里最常见的 ZPL 指令。下面这段是打印一张 50mm x 30mm 标签的完整指令每一行都有明确作用^XA ^LH0,0 ^FO50,50 ^A0N,32,32 ^FDHello Zebra^FS ^FO50,90 ^B3N,60,Y,N,N ^FD12345678^FS ^XZ逐行逻辑说明如下^XA开启标签格式^LH0,0设置原点偏移为 0也就是从标签左上角开始排版。^FO50,50是把后续内容的光标定位到距左边 50 点、距上边 50 点的位置注意这里单位默认是点dot203dpi 打印机上 1 点约等于 0.125mm。^A0N,32,32选择内置字体 0横向 32 点、纵向 32 点N表示不旋转。^FDHello Zebra^FS是实际要打印的文本内容^FS表示字段结束。后面^FO50,90重新定位^B3N,60,Y,N,N选择 Code 39 条码高度 60 点Y表示要打印可读字符最后^FD12345678^FS是条码内容。这里有一个新手容易忽略的参数^FO的坐标单位是点不是毫米。203dpi 的机器 1 点等于 0.125mm300dpi 的机器 1 点约等于 0.0846mm。同一份 PRN 文件在 203dpi 和 300dpi 的打印机上打出来物理尺寸会不一样。所以排查打印尺寸不对时先确认机器分辨率再回看坐标参数这两个因素至少占七成的原因。2.3 ZPL 指令的转义陷阱为什么文本里的^会被吃掉在 C# 里写 ZPL 字符串还有一个常见坑反斜杠和^这两个字符。C# 里\是转义前缀^本身不需要转义但如果你的标签内容里要打印^这个字符本身比如打印价格 ^500那^FD后面的500 会被解释成 ZPL 命令的开始而不是内容。正确做法是用^FH开启十六进制转义模式把特殊字符写成^5E 这种形式。string zpl ^XA\r\n ^FO50,50\r\n ^A0N,32,32\r\n ^FH\r\n // 开启十六进制转义才能打印 ^ 符号 ^FDPrice ^5E500^FS\r\n // ^5E 表示 ^ 字符本身 ^XZ\r\n;这段代码里^FH声明后面的字段内容里如果出现^开头的两位十六进制值会被按普通字符打印。^5E是^的 ASCII 码 0x5E 的十六进制表示。不加^FH时^FDPrice ^500会被打印机拆成^FDPrice和一个非法指令500轻则那一段不打印重则标签格式直接中断。我把这个点放在前面讲是因为后面所有生成 PRN 文件的代码都要带上这个意识。你在源码的测试文件生成逻辑里也要留出转义外理的位置否则测试内容稍微特殊一点就翻车。3. 拆解 FrmPrintLan工程结构、打印流程与关键代码3.1 源码包里的文件分别对应什么这份源码解压后是一个标准的 Visual Studio 解决方案项目名叫 SampleUtilsPrint核心窗体是 FrmPrintLan。先看整体文件构成搞清楚每个文件的存在意义后面改代码时才不会找错地方。文件/目录作用说明SampleUtilsPrint.sln解决方案文件用 Visual Studio 双击打开是编译入口SampleUtilsPrint.csproj项目文件记录目标框架、引用、编译选项Program.cs程序入口Main 方法启动 Winform 消息循环FrmPrintLan.cs主窗体逻辑按钮点击、文件读取、Socket 发送都在这里FrmPrintLan.Designer.csUI 布局控件初始化、位置、事件绑定FrmPrintLan.resources窗体资源图标、图片等嵌入资源app.manifest权限声明控制程序运行级别、兼容性bin / obj编译输出bin 是生成目录obj 是中间文件可删这个项目规模不大典型的三层关系Program.cs 负责启动FrmPrintLan.cs 负责交互与打印FrmPrintLan.Designer.cs 负责界面。如果你要加功能比如增加批量打印进度条改动集中在 FrmPrintLan.cs 和 Designer.cs 两处。3.2 Program.cs 和 app.manifest不起眼但影响运行的两个文件Program.cs 内容极短但对 Winform 程序来说是骨架using System; using System.Windows.Forms; namespace SampleUtilsPrint { internal static class Program { [STAThread] static void Main() { Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); Application.Run(new FrmPrintLan()); } } }[STAThread]是给 Windows Forms 消息机制用的线程模型声明必须保留否则剪贴板、拖放、通用对话框这些组件会出奇怪的问题。Application.Run(new FrmPrintLan())把主窗体推进消息循环程序就活起来了。app.manifest 里如果声明了requestedExecutionLevel为asInvoker程序不需要管理员权限就能运行这对接 9100 端口来说是合理的只有走 Windows 打印驱动映射网络打印机时才可能需要提权。如果后面发现装了运行库还是打不开,优先检查 bin 目录下有没有对应的 .exe.config 文件和 .NET Framework 版本匹配情况。3.3 核心发送逻辑把 PRN 文件字节流发到打印机 9100 端口FrmPrintLan 最核心的功能不是界面而是把 PRN 文件的字节流通过网络发到斑马打印机。斑马打印机默认开放 9100 端口用于 Raw TCP 打印这也是工业打印领域最常见的直连方式不需要安装任何驱动只要 IP 通、端口通发过去就是打印任务。FrmPrintLan 的 Lan 指的正是这种网络打印方式而不是 USB 或串口。private void btnSend_Click(object sender, EventArgs e) { // 从界面拿到打印机 IP端口固定为 9100 string printerIp txtIp.Text.Trim(); int port 9100; // 检查 PRN 文件是否已经选择 if (string.IsNullOrEmpty(txtPrnPath.Text)) { MessageBox.Show(请先选择 PRN 文件); return; } // 按原始字节读取避免编码转换破坏 ZPL 指令 byte[] data File.ReadAllBytes(txtPrnPath.Text); using (TcpClient client new TcpClient()) { client.Connect(printerIp, port); using (NetworkStream stream client.GetStream()) { // 一次性写入全部字节然后立即刷新 stream.Write(data, 0, data.Length); stream.Flush(); System.Threading.Thread.Sleep(300); } } }逻辑说明File.ReadAllBytes是这段代码的关键选择它把 PRN 文件当纯字节流处理不做任何编码转换这保证了 ZPL 指令在传输过程中不被改动。TcpClient是 .NET 封装好的 TCP 客户端Connect指定打印机 IP 和 9100 端口。写入数据后Flush确保数据进入网络最后Thread.Sleep(300)给打印机一点处理时间避免连接刚关闭数据还没发完。参数上值得留意的是如果网络环境较差或 PRN 文件较大300ms 可能不够可以调到 800ms但也不宜过长否则批量打印时效率很低。更规范的做法是把 Sleep 改成stream.Write后调用client.Client.Shutdown(SocketShutdown.Send)告诉对端数据发完了但有些老款斑马固件对这个握手处理得不好反而会丢最后一段数据。所以我个人倾向于保留 Sleep 方案实测兼容性最好。3.4 Designer.cs 和 resources界面文件里藏着可用控件清单FrmPrintLan.Designer.cs 是 Visual Studio 设计器自动生成的代码里面把窗体的控件都初始化好了。一个典型的打印测试窗体至少包含这些控件IP 地址文本框txtIp、PRN 文件路径文本框txtPrnPath、浏览按钮btnBrowse、发送按钮btnSend以及日志区域。InitializeComponent方法里每一个this.txtIp new TextBox()都对应界面上一个输入框。resources 文件里一般是窗体图标和背景图。改图标时直接用 Visual Studio 的资源编辑器替换即可不用手改代码。需要提醒的是如果你把窗体从 FrmPrintLan 复制改名成 FrmPrintUsbDesigner.cs 里的InitializeComponent里所有控件变量名也要跟着改否则编译报错一堆未定义字段。最快的办法是在解决方案里右键项目添加新窗体让设计器自动生成完整代码而不是手动复制。4. 避坑指南PRN 打印测试的五个常见翻车现场4.1 用记事本另存过 PRN 文件打印出来全是乱码现象PRN 文件打开再保存一次发送到打印机后标签内容缺字、出现方框或者直接打印出一堆指令文本。原因记事本默认按 ANSI 或 UTF-8 重写文件保存时可能加入 BOM 头并把 LF 换成 CRLF。ZPL 解释器对 BOM 非常敏感额外字节会被当成指令的一部分导致第一个字段错位。解决不要用记事本编辑 PRN 文件再另存。如果一定要改内容用 VSCode 或 Notepad 明确以编码为 ANSI保存。在 C# 代码里读取时强制用File.ReadAllBytes发送前不要经过任何字符串编码转换。4.2 点击发送没有反应9100 端口连不上但程序不报错现象界面提示发送成功打印机完全没动静程序也不抛异常。原因TcpClient.Connect只是建立了 TCP 连接如果打印机 IP 写错或者端口被防火墙拦Connect本身会抛异常但不报错而没反应的情况通常是连接到了某个中间设备比如路由器的管理端口或者对端接受了连接但没按 9100 协议处理。另外要排除一种情况打印机 IP 正确但打印任务被打印机的休眠策略挂起Send 过去后打印机在睡眠恢复过程中丢掉了数据。解决先用命令行验证连通性telnet 打印机IP 9100能连上说明网络是通的。再检查打印机面板上的 IP 是不是固定 IPDHCP 分配的地址重启后会变。打印机休眠问题可以在 ZPL 里加^ST,1或调整打印机设置里的休眠时间。4.3 打印出来是一段一段的指令文本而不是标签现象打印机吐出一张纸上面印着 XA FO50,50 这种命令片段而不是排版好的标签。原因PRN 文件内容不是完整的 ZPL 格式缺少^XA开头或者文件被前面加了一些普通文本。还有一种情况是文件格式是 EPL被当成 ZPL 发送了——老款 Eltron 机型如果固件设置为 EPL 模式收到 ZPL 指令就会原样打印。解决用十六进制工具比如 HxD看 PRN 文件头几个字节ZPL 文件头应该是5E 58 41即^XA。如果文件头是普通 ASCII 文本说明你打开的并不是真正的打印机指令文件。确认打印机固件语言模式在打印机面板按语言切换设为 ZPL 后重试。4.4 中文内容打出来是方框或问号现象英文正常中文全部变方块有些字干脆消失。原因ZPL 的默认字库是内置的 ASCII 字体不包含中文字形。打印机收到中文 GBK/UTF-8 编码数据后没有中文字库可用只能用替代符号渲染。解决有两条路。一是 ZPL 指令里加^CI28把编码切到 UTF-8然后确保 C# 侧以 UTF-8 编码发送前提是打印机固件里装了中文字库。二是用^A0N配合^FH把中文按 Unicode 十六进制转义书写这种方式对固件版本要求低但指令长度会明显增加。我在实际项目里优先用方案一同样一份 PRN 在固件版本老的机器上打不出中文时再退回方案二。4.5 标签只打一半TCP 连接关得太早现象标签上半部分正常下半部分缺失或者末尾的条码永远打不出来。原因stream.Write只是把数据交给操作系统网络栈不代表打印机已经收到全部字节。如果你的代码写的是client.Close()紧跟在Write之后连接一断对端还没读完的数据就被丢弃。我在前面代码里用Thread.Sleep(300)就是这个原因。解决发送完数据后给一个合理的等待窗口再关闭连接。300ms 对大多数 203dpi 的小标签足够但如果你传的是上百 KB 的大图 PRN建议用循环分批读取写入然后 Sleep 800ms 再关。另外一个更稳妥的变通做法发送完不立即关闭连接而是调用stream.Flush()后再读取stream.ReadByte()阻塞等待打印机返回状态——不过斑马 9100 端口默认不返回握手信息等不到响应反而会超时所以还是 Sleep 方案实战更实用。5. 从编译到联调跑通源码并批量生成自己的测试 PRN5.1 Visual Studio 环境要求与编译步骤这份源码是 C# Winform 项目目标框架大概率是 .NET Framework 4.x。用 Visual Studio 2019 或 2022 都可以打开不需要额外装 NuGet 包因为核心依赖只有System.Net.Sockets和System.IO这俩都是 .NET Framework 内置程序集。编译步骤就三步用 VS 打开 SampleUtilsPrint.sln等还原完成解决方案配置选 Debug 或 Release生成项目。F5 直接跑也行编译产物在 bin\Debug 或 bin\Release 目录下exe 可以直接拷贝到别的 Windows 机器上运行前提是那台机器装了对应版本的 .NET Framework。如果目标机器是 Win7尽量用 .NET Framework 4.0 编译Win10/11 直接 4.8 没问题。5.2 写一个批量生成测试 PRN 的小工具调试斑马打印时手动改 ZPL 字符串效率太低。我一般会把这个逻辑直接塞到源码项目里做成一个独立方法通过循环生成不同内容的 PRN 文件再用窗体里的发送按钮逐个打出来。private void GenerateTestPrnFiles(string outputDir) { // 测试三种典型内容纯文本、条码、中文 string[] testContents new string[] { Text-Only-Label, BARCODE-2024-001, 中文标签测试 }; for (int i 0; i testContents.Length; i) { // 根据内容类型拼接不同的 ZPL string zpl; if (i 1) { zpl ^XA\r\n ^FO30,30\r\n ^B2N,80,Y,N,N\r\n // Code 128 条码 ^FD testContents[i] ^FS\r\n ^XZ\r\n; } else { zpl ^XA\r\n ^CI28\r\n // 中文用 UTF-8 ^FO30,30\r\n ^A0N,36,36\r\n ^FD testContents[i] ^FS\r\n ^XZ\r\n; } // 以 ASCII 编码写成 .prn注意不要带 BOM string fileName Path.Combine(outputDir, test_ i .prn); File.WriteAllText(fileName, zpl, Encoding.ASCII); } MessageBox.Show(生成完成共 testContents.Length 个 PRN 文件); }逻辑说明这里区分了条码与普通文本两种 ZPL 结构。条码用^B2N生成了 Code 128 格式高度 80 点带可读字符中文内容先加^CI28再写文本。注意写入文件时用了Encoding.ASCII有人说中文用 ASCII 会丢失确实如此但这里有个细节对于 ASCII 编码中无法表示的字符Encoding.ASCII会把它们替换成?也就是说中文标签会打出 ?? 而不是乱码更容易暴露出没有中文字库这个真实问题。如果打印机装了中文字库这里应改用Encoding.UTF8配合^CI28才能打出真正的汉字。5.3 把生成器接入窗体一个按钮完成批量打印验证上面生成的多个 PRN 文件如果一个一个手动加载再发效率很低。我在实际项目中会在 FrmPrintLan 窗体上加一个批量发送按钮遍历目录下所有 .prn 文件逐个走 TCP 发送。private void btnBatchSend_Click(object sender, EventArgs e) { string dir txtPrnPath.Text; // 复用已有路径输入框这里传目录 if (!Directory.Exists(dir)) { MessageBox.Show(请输入有效目录路径); return; } string[] prnFiles Directory.GetFiles(dir, *.prn); using (TcpClient client new TcpClient()) { client.Connect(txtIp.Text.Trim(), 9100); NetworkStream stream client.GetStream(); foreach (string file in prnFiles) { byte[] data File.ReadAllBytes(file); stream.Write(data, 0, data.Length); stream.Flush(); // 每份文件间隔 500ms避免打印机处理不过来 System.Threading.Thread.Sleep(500); } } MessageBox.Show(批量发送完成共 prnFiles.Length 个文件); }复用同一个 TcpClient 是这里的关键优化不用每发一个文件重新握手一次一个连接里连续写完所有任务。斑马打印机对同一连接里的连续任务有良好支持每个^XZ会被识别为一个独立的标签任务。如果打印过程中发现第 3 个文件之后内容丢失多半是打印机接收缓冲满了这时把 Sleep 从 500ms 加到 1500ms或者拆成每 5 个文件重连一次。5.4 联调前的检查清单从源头上降低翻车概率在把源码绑定到业务系统之前我强烈建议先把这几项环境信息列成表格逐一确认因为这些变量任何一个不对后面排查都要花双倍时间。检查项期望值排查方式打印机 IP与电脑同网段打印机面板网络设置9100 端口开放telnet IP 9100固件语言ZPL打印机面板语言设置打印机分辨率203/300dpi面板或机身上铭牌中文字库已安装或不用中文打印配置页确认PRN 文件编码无 BOMHxD 查看文件头这套清单是我每接一个新项目必走一遍的流程。清单一过剩下的问题基本都能定位到源码逻辑本身。6. 验证打印效果的进阶技巧先用命令行确认打印机通了再谈工具如果你手头暂时没有 Visual Studio或者想在改源码之前先确认打印机这条链路是通的Windows 自带的 PowerShell 就能完成 FrmPrintLan 做的一半事情。这一步验证很有价值它能帮你把工具的问题和打印机/网络的问题快速切分开避免在源码里查半天才发现是打印机 IP 写错了。$ip 192.168.1.100 $data [System.IO.File]::ReadAllBytes(C:\temp\test.prn) $client New-Object System.Net.Sockets.TcpClient $client.Connect($ip, 9100) $stream $client.GetStream() $stream.Write($data, 0, $data.Length) $stream.Flush() Start-Sleep -Milliseconds 500 $client.Close()这段命令和 C# 代码做的事情一模一样读字节、连 9100、写数据、等待、关闭。如果这段命令能让打印机出纸说明网络和打印机都没问题问题在工具本体如果这段命令也不行你就直接去查打印机 IP 和端口不需要盯着 Visual Studio 里断点纠结。我现在的习惯是每次拿到斑马打印机的新项目先手动构造一个最简的^XA^FO50,50^A0N,30,30^FDHello^FS^XZ存成 test.prn用 PowerShell 或 FrmPrintLan 任选一种方式打出来。二三十秒的事情却能排除掉八成环境类故障。从那以后我在任何打印集成项目里都强制先走一遍这个最小验证再进入批量测试和复杂标签开发。希望这套从指令结构到源码落地再到排查手法的流程能帮你在斑马打印机的调试路上少走一点弯路。本文还有配套的精品资源点击获取