微信小程序的打印功能，是很多开发者容易踩坑的地方。你可能会发现，明明在电脑上调试得好好的，一上手机就“打印无反应”或者“预览乱码”。别急着怀疑自己代码写错了，这背后的坑往往出在“蓝牙协议”和“指令格式”上。今天我们就从真实场景出发，把打印这件事彻底聊透。

一、先搞清楚你的打印机属于哪一类

市面上常见的小票打印机分为三种：蓝牙打印机（如佳博、芯烨）、Wi-Fi打印机（通过局域网连接）、云打印机（通过服务器中转）。微信小程序里最常用的是蓝牙打印机，因为不需要额外配置网络，用户打开手机蓝牙就能用。但要注意：微信小程序只支持低功耗蓝牙（BLE），如果你的打印机是传统蓝牙（如SPP协议），那小程序根本搜不到设备。买打印机前务必确认支持BLE。

二、小程序里实现打印的完整流程（附代码）

假设你用的是佳博58mm热敏蓝牙打印机，流程分四步：搜索设备 → 连接设备 → 发送指令 → 断开连接。卡在“发送指令”这一步，因为打印机只认ESC/POS指令集，而不是普通文本。比如你想打印“你好”，不能直接发字符串，要转成十六进制字节：0x1B 0x40（初始化指令）+ 0x0A（换行）+ 文本的GBK编码。这里有个坑：微信小程序默认不支持GBK编码，安卓和iOS的编码方式还不一样。推荐用TextEncoder转UTF-8，但部分打印机不认，这时候就得用第三方库（如iconv-lite的微信移植版）转码。

举个具体例子：打印“订单号：123”加上二维码。你需要先发初始化指令1B 40，然后发文本指令1B 21 00（字体大小），接着发二维码指令1D 6B 48 0A 31 32 33（0A是二维码内容长度，后面跟内容）。这些指令在打印机手册里都能找到，但建议直接下载现成的指令生成库，比如escpos-tool，避免自己拼错字节。

三、最常见的三个报错及根治方法

错误1：搜索不到设备
原因：手机蓝牙权限没开，或者打印机没进入配对模式。解决方法：让用户去系统设置里打开位置权限（安卓必须开位置才能搜蓝牙），同时长按打印机电源键3秒听到“滴”声再搜。

错误2：连接成功但打印空白
原因：发送的指令格式不对。比如你发了UTF-8编码的中文，但打印机只认GBK。可以试试在发送前用ArrayBuffer转码：
const buffer = new ArrayBuffer(text.length * 2);
const view = new DataView(buffer);
for (let i = 0; i < text.length; i++) { view.setUint16(i * 2, text.charCodeAt(i), true); }
然后通过writeBLECharacteristicValue发送。如果还是空白，换一台打印机测试——有些廉价打印机对指令兼容性极差。

错误3：打印内容乱码或错位
原因：没有在打印前发送初始化指令。每次打印前必须发送0x1B 0x40，否则打印机可能处于上次打印的“半截状态”。还有可能是你一次性发送的数据太长，BLE单次传输最大20字节，超过要分包发送，但分包间隔不能太短（建议50ms以上），否则打印机处理不过来。

四、比打印功能更重要的“用户体验”细节

做完打印功能就急着上线，结果用户反馈“打印失败后不知道怎么办”。这里分享两个提升体验的技巧：

1. 增加重试机制：打印失败时不要直接弹“错误”，而是自动重试一次。因为蓝牙连接偶尔会丢包，重试后成功率能到90%以上。
2. 提供“打印预览”：用canvas绘制出要打印的内容，让用户确认排版。比如小票上的“商品名称”和“价格”是否对齐，预览能提前发现字体过小或截断的问题。这个功能反而比打印本身更能减少客服咨询量。

五、对比几种方案的优劣：原生开发 vs 第三方服务

如果你不想自己处理蓝牙协议和指令编码，可以接入第三方打印服务，比如易联云、飞鹅。它们的SDK封装了连接和指令，你只需要调用API传数据。但代价是：
- 成本：按打印次数收费（约0.1-0.5元/次），量大不划算。
- 依赖网络：必须联网，不像蓝牙打印可以离线用。
- 定制化：如果你要打印特殊格式（如带logo的发票），自己写指令更灵活。

举个例子：一家奶茶店用蓝牙打印小票，每单成本几乎为0；如果用云打印，一天500单就要50元。所以月打印量超过1000单时，建议自己开发蓝牙方案。

六、扩展：用小程序打印标签（不限于小票）

除了热敏小票，很多场景需要打印不干胶标签（如快递面单、价格标签）。这类打印机（如TSC、斑马）用的指令集不同，通常是ZPL或EPL。在小程序里发送ZPL指令的原理和ESC/POS一样，但要注意：标签打印机的分辨率更高（203dpi或300dpi），坐标计算要精确到像素。比如打印一个5cm×3cm的标签，宽度是5*203/25.4≈40个点，高度是3*203/25.4≈24个点。你需要用^FO指令定位文字位置，^BY设置条码参数。如果嫌麻烦，可以用jszpl这类库生成指令字符串，再通过蓝牙发送。

七、一个容易被忽略的坑：小程序后台的蓝牙权限配置

在微信公众平台的小程序后台，必须勾选“蓝牙”和“附近设备”权限。忘了这一步，导致在真机上始终提示“未授权”。另外，iOS端从微信8.0.0版本开始，蓝牙连接必须由用户主动触发，不能自动连接。所以设计UI时，要放一个“点击连接打印机”的按钮，而不是一进页面就自动搜索。

最后说一句：如果你测试时发现安卓能打印但iOS不行，大概率是特征值UUID的问题。不同打印机厂商对UUID的定义不同，有些需要从serviceId中动态获取特征值，而不是写死。建议在连接成功后打印所有特征值，手动选择那个write权限的UUID。