简介面向刚接触 TSC 标签打印开发的初学者这份压缩包提供可直接接入项目的第三方库文件与配套资料重点解决 DLL 部署、LIB 导入和头文件引用等环境配置问题也适用于需要在 Windows 项目中实现标签打印、二维码打印的开发者快速核对依赖是否齐全。包内共 8 个文件以 lib、h、dll 三类开发文件为主分别对应静态导入库、函数声明头文件与运行时动态库并附带驱动安装程序和 TSPL 中文文档压缩包约 18.89MBWin32 与 X64 两套目录结构便于按目标平台取用避免自行编写函数声明或反复查找版本。已有 507 人学习说明其在同类入门资料中具备一定参考价值。读者可获得较完整的库文件组合、平台区分清晰的目录组织以及可对照查阅的中文指令文档和驱动安装包适合作为 TSC 打印机二次开发的基础素材。1.TSC 打印机接进项目那天我以为装上驱动就完事了。结果标签打印能出纸二维码打印出来糊成一团换 64 位编译后直接抛BadImageFormatException一个下午全耗在位数和端口上。这类现场太常见产线上摆一台 TSC 标签机上位机要按单号实时打条码和二维码开发包解压出来一堆文件看着都有用真装起来驱动、DLL 位数、串口参数、TSPL 指令四处都能翻车。代价很实在不是报错是打半张、走纸错位、扫不出来产线停下来等你调。下面按环境清单、驱动连接、DLL 调用、指令排版、排错、验证的顺序写写给第一次接标签机的开发者也写给接过但被位数坑过的老手走完能稳定出标签。2. 环境清单与驱动安装位数、运行库、USB 与 9100 三条路动手前先定两件事这份开发包里的东西分别管哪一段以及你的程序是 32 位还是 64 位。这两件不定后面每步都白折腾。我一般先把压缩包解开摆在一个固定目录比如C:\tsc\不放在桌面或下载目录因为后面要在代码里写绝对路径路径里有空格或中文是另一类玄学问题。2.1 包里四类东西先分清谁管哪一段解压出来别急着双击 exe先按用途归类。标签机开发包通常就四类文件混着放会让人以为随便挑一个就能用。组件位数作用什么时候必须用函数库 DLL32 位x86提供 openport / sendcommand 这类接口程序编译成 x86或跑在 32 位解释器里函数库 DLL64 位x64同上供 64 位进程加载程序是 x64或 64 位 Python 调用ActiveX 控件x86 为主COM 组件拖控件或网页里嵌老式桌面端、需要控件预览的界面Windows 打印驱动全平台建打印队列让系统认这台机器想走系统打印、要预览、要共享DLL 那一份是核心驱动是可选项。很多人一上来先装驱动装完发现程序里调不到接口其实驱动只负责让 Windows 认识这台机器跟你在代码里发指令是两条路。走 DLL 路线时驱动不是必需的但装了不亏因为自检页、校准、端口排查都要靠它。ActiveX 那份现在用得少只在维护老系统时碰。真要用得用管理员权限注册注册完 32 位和 64 位的注册表位置不一样这一步后面排错章会细说。提示把 32 位和 64 位两份 DLL 分开放两个目录比如C:\tsc\x86\和C:\tsc\x64\。放在一起早晚拿错而拿错的报错信息完全看不出是拿错。2.2 位数取舍x86、x64 与 AnyCPU 的三种结局位数是这套环境里最容易翻车的地方血泪经验报错说「试图加载格式不正确的程序」八成就是位数对不上跟代码逻辑一点关系没有。三种结局要记清楚。编译成 x86进程是 32 位只能加载 32 位 DLL稳。编译成 x64进程 64 位只能加载 64 位 DLL。编译成 AnyCPU 最坑在 64 位系统上默认起 64 位进程你以为自己没选其实已经被判成 64 位了然后加载 32 位 DLL 直接崩。改起来很简单在项目文件里钉死PropertyGroup !-- AnyCPU 在 64 位系统上默认起 64 位进程加载 32 位 DLL 必炸 -- PlatformTargetx86/PlatformTarget !-- 只对 exe 生效类库项目不需要这一行 -- Prefer32Bittrue/Prefer32Bit /PropertyGroupPlatformTarget决定输出程序集的位数Prefer32Bit是给 AnyCPU 的 exe 加的一层保险让它优先以 32 位启动类库项目里写这行没意义。改完记得清一次bin和obj旧产物不清跑的还是老位数。Python 这边更直接解释器位数决定一切。先确认自己用的是哪个# 输出 32 说明是 32 位解释器输出 64 就是 64 位 python -c import struct; print(struct.calcsize(P) * 8)32 位 Python 只能加载 32 位 DLL64 位只能加载 64 位。装了两个 Python 环境时尤其注意命令行里python指向的那个不一定是你 IDE 里用的那个这一步错了后面WinDLL一调就抛OSError [WinError 193]。2.3 驱动安装USB 认口、网口 9100、串口对波特率三条连接路径选一条就行不用全上。USB 最省事。装驱动插线设备管理器里出现打印机队列就成了。TSC 的 USB 口在代码里通常直接写USB当端口名不用管它到底映射到哪个虚拟端口。缺点是换台机器要重装驱动产线上多台机器部署时麻烦。网口是我最推荐的。打印机接网线自检页上会打出当前 IP把电脑和打印机放同一个网段先 ping 通再用 9100 试。9100 是打印机的 RAW 端口收到什么字节就打什么完全绕过驱动和打印队列程序里一个 TCP 连接就能发标签。部署时改个 IP 就完事比 USB 好维护太多。import socket # 9100 是打印机最常见的 RAW 端口收到什么字节就打什么不走驱动 cmd ( SIZE 60 mm,40 mm\r\n GAP 2 mm,0 mm\r\n CLS\r\n TEXT 30,30,3,0,1,1,PORT 9100 OK\r\n PRINT 1,1\r\n ) with socket.create_connection((192.168.1.50, 9100), timeout5) as s: s.sendall(cmd.encode(ascii))每行指令必须以\r\n结尾少一个回车打印机就不认这是纯文本协议不是 JSON容错为零。SIZE和GAP先按实际标签写先别纠结排版能出一张纸就算链路通了。CLS清画布PRINT 1,1是打一份一张两个参数分别是份数和张数。串口是老设备上常见的COM3这种端口号会随插拔变化别写死在配置里。波特率必须和打印机自检页上显示的一致常见 9600 或 1152008 位数据位、无校验、1 位停止位。对不上就是乱码或者一堆空白纸。2.4 先打一张自检页把硬件这半边钉死驱动装完、线接好第一件事不是写代码是按住面板上的 FEED 键再开机让打印机自己打一张自检页。这张纸上有型号、当前 DPI、通讯参数、IP、已打印里程。DPI 尤其关键203dpi 和 300dpi 的坐标换算差了一大截后面排版全靠它。自检页能出来说明硬件、耗材、走纸都正常问题一定在软件侧排查范围立刻缩一半。出不来就先别碰代码查碳带、标签纸、间隙传感器。3. TSCLIB.dll 调用C# 与 Python 各写一份最小可用代码函数库这层其实很薄本质是把 TSPL 指令拼好往下发用不着背几十个函数。我通常只用七个够覆盖打标签的全部场景。3.1 够用的函数就这几个函数作用容易忽略的点openport打开端口返回 0 才是成功网口写 IPUSB 写USBcloseport关闭端口不关会占用端口下次打开失败clearbuffer清空画布不清会把上一张的内容叠上来sendcommand下发任意 TSPL 指令最灵活排版基本靠它printlabel出纸两个参数份数、张数printerstatus查状态缺纸、开盖、卡纸都从这里读windowsfont调系统字体打中文只在 Windows 下有效sendcommand是关键学会它就等于学会了全部。上面那些TEXT、BARCODE、QRCODE全都能当字符串塞进去不用一个个找对应的封装函数。封装函数的好处是参数有类型检查坏处是新指令用不了还得等厂商更新。3.2 C# 的 DllImport 写法和调用顺序C# 这边用DllImport声明重点在CharSet和CallingConvention这两个写错就是返回一堆乱值或者直接内存报错。using System; using System.Runtime.InteropServices; internal static class Tsc { // 32 位进程写 TSCLIB.dll64 位进程写 TSCLIB_x64.dll写错就是 DllNotFound private const string Dll TSCLIB.dll; // 字符串参数一律按 ANSI 传调用约定按 StdCall [DllImport(Dll, CharSet CharSet.Ansi, CallingConvention CallingConvention.StdCall)] public static extern int openport(string port); [DllImport(Dll, CharSet CharSet.Ansi)] public static extern int closeport(); [DllImport(Dll, CharSet CharSet.Ansi)] public static extern int sendcommand(string cmd); [DllImport(Dll, CharSet CharSet.Ansi)] public static extern int printlabel(string sets, string copies); } // 调用顺序固定开端口 → 下发指令 → 出纸 → 关端口 if (Tsc.openport(USB) ! 0) // 网口写 192.168.1.50串口写 COM3 throw new Exception(openport 失败先查端口名和驱动); try { var tspl SIZE 60 mm,40 mm\r\n GAP 2 mm,0 mm\r\n CLS\r\n QRCODE 40,40,H,5,A,0,\https://example.com/p/10086\\r\n TEXT 40,200,\3\,0,1,1,\A-001\\r\n PRINT 1,1\r\n; Tsc.sendcommand(tspl); Tsc.printlabel(1, 1); // 1 份1 张 } finally { Tsc.closeport(); // 放 finally 里异常也要关 }printlabel的两个参数是字符串不是整数这是历史遗留传1不要传1。closeport一定放finally否则中间抛异常端口就一直被占着下次打开返回非 0现场表现是「刚才还能打重启程序就不行了」。DLL 要拷到 exe 同级目录或者放系统目录。放System32的做法我不推荐多版本并存时会互相覆盖出问题很难查。3.3 Python 用 ctypes 走一遍同样的流程Python 没有编译期问题全在运行时暴露所以argtypes和restype一定要写全。不写的话 ctypes 默认按 int 处理指针64 位下指针被截断表现是随机崩溃或者打出一堆乱码。import ctypes from ctypes import c_char_p, c_int # 位数必须和解释器一致64 位 Python 只能加载 x64 那份 lib ctypes.WinDLL(rC:\tsc\x86\TSCLIB.dll) lib.openport.argtypes [c_char_p] lib.openport.restype c_int lib.sendcommand.argtypes [c_char_p] lib.printlabel.argtypes [c_char_p, c_char_p] lib.closeport.restype c_int TSPL ( SIZE 60 mm,40 mm\r\n GAP 2 mm,0 mm\r\n DIRECTION 1\r\n CLS\r\n QRCODE 40,40,H,5,A,0,https://example.com/p/10086\r\n TEXT 40,200,3,0,1,1,A-001\r\n PRINT 1,1\r\n ) ret lib.openport(bUSB) # 网口写 b192.168.1.50串口写 bCOM3 if ret ! 0: raise RuntimeError(fopenport 失败返回 {ret}) try: lib.sendcommand(TSPL.encode(ascii)) # 整段 TSPL2 一次下发 lib.printlabel(b1, b1) # 1 份1 张 finally: lib.closeport()字符串一律传字节bUSB不是USB。内容里有中文时encode(ascii)会直接抛异常这是好事比打到纸上变乱码强中文的正确处理方式在第 4 章说。3.4 什么时候干脆不用 DLL服务端 socket 直发只要走网口DLL 根本不是必需品。Linux 服务器、Docker 容器、无驱环境里跑打印服务用 socket 直发 TSPL 就是标准做法还省掉位数和运行库两个坑。判断标准很简单需要调windowsfont打中文、或者要用打印机状态回读走 DLL纯排版出纸直发就够了。直发的代价是没有返回值发出去不知道打印机收没收到所以得靠业务侧的确认机制补比如打完让操作员扫一下。4. TSPL2 二维码与排版QRCODE 指令逐参数拆开看标签打得好不好八成取决于指令里那几个数字。二维码糊、扫不出、位置偏基本都是参数拍脑袋写造成的。4.1 QRCODE 六个参数改哪个影响扫码率基本格式是QRCODE x,y,纠错等级,单元宽度,模式,旋转,内容。看着简单每个位置都有讲究。位置参数常用值影响1-2x, y点坐标原点左上受DIRECTION影响3纠错等级LMQH越高越耐污损但码更大4单元宽度3~10 点太小扫不出太大放不下5模式A自动一般不手动指定6旋转0 / 90 / 180 / 270竖版标签常用 90纠错等级是第一个要决策的。H 级能容忍约 30% 面积污损代价是同样内容码会大一圈。小标签上放长 URL选 H 就容易溢出边界这时要么降到 Q要么换短链接。我的习惯是内容短就上 H内容长先算尺寸再定。单元宽度直接决定扫码率。203dpi 下 4 个点约 0.5mm是能稳定扫出的下限再小就要看扫码枪质量和打印浓度了。小标签上为了塞进去把宽度压到 2现场十有八九扫不出。SIZE 60 mm, 40 mm GAP 2 mm, 0 mm DIRECTION 1 CLS QRCODE 40,40,Q,5,A,0,https://example.com/p/10086 TEXT 40,200,3,0,1,1,A-001 PRINT 1,1这段可以直接粘到 9100 端口里试。DIRECTION 1是出纸方向改 0 就是反的坐标全部跟着变排版错乱时先看这一行。4.2 一维码、文字和中文字体的三条路一维码格式是BARCODE x,y,类型,高度,是否显示字符,旋转,窄条宽,宽条比,内容。类型写128最通用EAN13这类有校验位要求长度不对直接不打。文字用TEXT x,y,字体号,旋转,x 倍宽,y 倍高,内容。字体号从1到5数字越大点阵越大0是矢量字体缩放不糊但打印机固件要支持。中文有三条路按场景选一是 Windows 下用windowsfont直接调系统里的中文字体简单但只在 DLL 路线可用内容和字体都不进打印机。二是CODEPAGE配合内置字库把代码页设成和内容编码一致适合固定短语比如「合格品」「待检」。三是把 TrueType 字库文件下到打印机存储里再用TEXT引用。脱机打印、不想依赖上位机时用这个代价是要提前把字库推上去换字体得重新推。三条路混用会乱码。我见过同一个项目里一部分标签走windowsfont、一部分走代码页结果一半中文正常一半是方框查了两天才发现是两套逻辑。4.3 坐标与 DPI毫米换算成点别拍脑袋写数字TSPL 的坐标单位是点不是毫米。203dpi 是每英寸 203 点也就是 1 毫米约 8 点300dpi 约 11.8 点。同一个40在两种机器上差了一小截跨机型部署时排版全乱。换算写成函数别在心里估def mm2dot(mm: float, dpi: int 203) - int: 把毫米换算成打印点dpi 从自检页上读不要猜 return round(mm * dpi / 25.4) # 60mm 宽的标签在 203dpi 下是 480 点在 300dpi 下是 709 点 print(mm2dot(60, 203), mm2dot(60, 300))排版时我一般把关键位置都写成函数调用比如左边距mm2dot(3)。换机型只改 dpi 一个参数不用重新数一遍坐标。硬写数字的项目换批机器就得重排一遍这是实打实的返工。4.4 校准与纸型SIZE、GAP、BLINE 对不上就白打SIZE必须和实际标签尺寸完全一致写大了图纸上留白写小了内容被裁。GAP是间隙纸的间隙高度常见 2mm 或 3mm黑标纸要用BLINE方向写错就一直报找不到标记。换纸型之后一定要重新校准。多数机型是关机按住 PAUSE 再开机等它自己走几张纸停住这时候测出来的纸长才准。不校准直接打表现是每张往下偏一点打十来张就整体错位这种累积偏移靠调坐标治不好只能重新测纸。5. 避坑与排查五条踩坑记录每条都有后悔药下面五条都是我实际撞过的按「现象 → 原因 → 解决」写遇到问题时可以直接对号入座。5.1 装的时候翻的车位数、运行库、openport第一条一运行就抛BadImageFormatException。现象是编译完全正常new出对象那一刻崩异常信息里提到「格式不正确的程序」。原因是进程位数和 DLL 位数不一致最常见的是 AnyCPU 项目在 64 位系统上跑成 64 位进程加载了 32 位 DLL。解决是把PlatformTarget钉成x86或者换成 x64 那份 DLL改完清bin、obj再编。这条没有别的可能看到这个异常直接查位数别怀疑代码。第二条DllNotFoundException提示找不到模块。现象是 DLL 明明在项目里引用也加了运行还是找不到。原因有三个DLL 没拷到输出目录DLL 依赖的 VC 运行库没装32 位程序加载了 64 位 DLL这时报的是找不到不是格式错误容易误判。解决是把 DLL 放 exe 同级装对应位数的 VC 运行库32 位程序装 x86 版64 位装 x64 版两个都装也不冲突。有依赖查看工具的话直接看它缺哪个 dll比猜快得多。第三条openport返回非 0。现象是程序不崩但一张纸都不出。原因依次排查端口名写错网口写 IP 不写\\192.168...USB 就写USB驱动没装导致 USB 口不可用端口被别的程序占着上一个进程没closeport打印机不在同一网段。解决顺序是先 ping 通、再自检页确认 IP、再单独跑一个最小脚本调openport一层层缩小范围。别在业务代码里加日志猜写个十行的测试脚本最快。5.2 打出来不对的时候半张标签和扫不出的二维码第四条标签只打半张或者每张多走一截。现象是内容打在两张纸的接缝上越打越偏。原因是SIZE和实际纸尺寸不符、GAP值不对、或者换纸后没重新校准。解决是先量纸把SIZE改成实测值GAP按间隙纸实际厚度改然后按住 PAUSE 开机重新测纸。还有一点容易被忽略DIRECTION改了之后坐标原点位置也变之前调好的坐标要整体重算。第五条二维码打出来能看就是扫不出。现象是肉眼能看出是个码扫码枪贴近了也读不到。原因通常是单元宽度太小低于 3 点、纠错等级太低、打印浓度不够导致黑白对比不足、或者内容太长把码挤到边界。解决是把单元宽度提到 5 以上、纠错等级升到 Q 或 H、把浓度调高一两档、内容换成短链接。改完别只看纸面一定用现场那把扫码枪实测手机扫得出不代表产线那把扫得出。6. 装完怎么验证四个检查点一次跑通再交付装完不等于能用。我现在交付前固定走四步每步都有明确的判定标准任何一步不过就停在那儿查不往下走。检查点判定标准失败先看哪硬件链路自检页能打出IP 和 DPI 可读耗材、间隙传感器、网线端口连通9100 能建连openport返回 0端口名、驱动、同网段指令通路能打出一行纯英文文本\r\n结尾、SIZE、CLS业务完整二维码 一维码 中文同张出纸扫码枪能读编码、字库、单元宽度前两步是环境问题后两步是内容问题。这个顺序不能颠倒端口没通就去调二维码参数纯属浪费时间。第三步我一般用一行命令确认比开 IDE 快# 只验端口不管内容能连上就说明网络和打印机都在线 python -c import socket;ssocket.create_connection((192.168.1.50,9100),3);print(port ok);s.close()打印机能连上但不出纸就在指令里找原因八成是某一行少了\r\n。第四步是最容易被跳过的一步很多人打完看到二维码就收工结果一维码的校验位长度不对或者中文在 300dpi 机器上糊成一片。所以最终验证一定要在一张标签上把三种内容全放上去用现场的扫码枪扫一遍扫得出再交付。还有一个习惯把验证用的那段指令单独存成一个文本文件放在项目里叫selftest.txt。换机器、换现场、过两个月回来接手双击发一遍就知道环境还活着没有。这东西比任何文档都可靠。从那以后我每次接标签机项目都强制先打自检页、再跑一遍四步验证哪怕客户催得急也不跳。跳过的那次我在产线边上站了三个小时最后发现是 AnyCPU 的老问题。希望这套流程能帮你少站那几个小时。本文还有配套的精品资源点击获取