手机连打印机保姆级教程：3步搞定API变更痛点

版本升级后 API 全变了？别慌，这份保姆级教程带你避坑。很多人卡在蓝牙协议和权限配置上，浪费半天时间。今天直接上干货，对比主流方案，代码全给你。

方案定位：谁在统治手机打印领域

在手机连接打印机的技术栈里，主要有三条路线：系统原生 API、第三方 SDK、以及纯底层协议直连。新手最容易踩的坑，就是分不清这三者的边界。选错了路线，后期维护成本会呈指数级上升。

Android 原生 Print Framework 是系统级的，从 Android 4.4 开始引入，Android 8.0 后逐步成熟。它的优势在于无需额外依赖，直接调用系统服务。缺点是文档晦涩，API 变动频繁，特别是从 PrintJob 到 PrintDocumentAdapter 的迁移，让很多老项目代码失效。

Epson Connect / HP Smart SDK 等厂商 SDK 则是另一条路。它们封装了复杂的网络协议，提供开箱即用的体验。但绑定特定品牌，跨品牌兼容性差，且 SDK 版本更新滞后于硬件迭代。

Bluetooth Socket 直连 适合极客和特定场景。直接通过 RFCOMM 或 SPP 协议发送 ESC/POS 指令。灵活度最高，但需要处理底层字节流，调试难度大，对蓝牙权限要求极高。

核心差异对比：一张表看懂优劣

为了让大家直观理解，我们把这三种方案的核心维度拉出来对比。注意，这里的“难度”是相对概念，基于 3 年以上后端开发经验评估。

维度	Android 原生 API	厂商 SDK (以 Epson 为例)	Bluetooth Socket 直连
适用系统	Android 4.4+	Android 5.0+ / iOS 9+	Android 4.3+ / iOS 不支持
依赖库大小	无额外依赖	15-30 MB	无额外依赖
权限复杂度	中等 (WRITE_EXTERNAL_STORAGE)	高 (网络+定位+存储)	极高 (BLUETOOTH_ADMIN)
API 稳定性	低 (每版本微调)	中 (随固件更新)	高 (协议标准不变)
调试友好度	差 (日志分散)	中 (有官方日志)	好 (Wireshark 可抓包)
跨品牌支持	是 (依赖 CUPS 服务)	否 (仅自家品牌)	是 (需自行适配指令集)
学习曲线	陡峭	平缓	极陡峭
维护成本	高 (需跟进系统更新)	中 (需跟进 SDK 更新)	低 (协议标准化)

关键发现：原生 API 的“低稳定性”是最大痛点。 Android 12 后，后台蓝牙扫描权限被收紧，导致大量旧版连接代码失效。这就是为什么很多开发者在版本升级后，发现 API 全变了。厂商 SDK 虽然稳定，但体积臃肿，且无法用于非合作品牌打印机。直连方案虽然硬核，但一旦协议解析正确，几乎永不维护。

代码写法对比：从入门到精通

下面给出三种方案的精简代码示例。注意，这些代码已去除冗余日志，聚焦核心逻辑。实际项目中，务必添加异常处理和超时机制。

1. Android 原生 API 实现

import android.print.PrintAttributes;
import android.print.PrintDocumentAdapter;
import android.print.PrintJob;
import android.print.PrintManager;
import android.graphics.pdf.PdfDocument;
import android.graphics.Canvas;
import android.graphics.Paint;
import android.os.ParcelFileDescriptor;
import android.content.Context;public class NativePrinterExample {private Context context;public void printPdf() {PrintManager printManager = (PrintManager) context.getSystemService(Context.PRINT_SERVICE);// 生成 PDF 文档PdfDocument document = new PdfDocument();PdfDocument.PageInfo pageInfo = new PdfDocument.PageInfo.Builder(100, 100, 1).create();PdfDocument.Page page = document.startPage(pageInfo);Canvas canvas = page.getCanvas();Paint paint = new Paint();paint.setTextSize(30);canvas.drawText("Hello Printer", 10, 50, paint);document.finishPage(page);ParcelFileDescriptor parcelFileDescriptor = new ParcelFileDescriptor.AutoCloseInputStream(new java.io.ByteArrayInputStream(new byte[0]) // 实际需写入 PDF 字节流);// 创建适配器PrintDocumentAdapter adapter = new PdfDocument.PageContent(page); // 简化示意，实际需自定义 Adapter// 设置打印属性PrintAttributes printAttributes = new PrintAttributes.Builder().setMediaSize(PrintAttributes.MediaSize.ISO_A4).setResolution(new PrintAttributes.Resolution("dpi", "DPI", 600, 600)).setColorMode(PrintAttributes.ColorMode.COLOR).build();// 发起打印任务printManager.print("MyTag", adapter, printAttributes);}
}

逐行解析： PrintManager 是入口，获取系统打印服务。 PdfDocument 是内存中的文档对象，需转换为 ParcelFileDescriptor 供系统读取。 PrintAttributes 定义了纸张、分辨率等参数，A4 是默认值，小票机需改为 CUSTOM。注意 print() 方法是异步的，需监听 PrintJob.Callback 获取结果。 API 变动点：Android 8.0 后，PrintDocumentAdapter 的 onLayout() 方法参数类型变更，需适配。

2. 厂商 SDK (Epson Connect) 实现

import com.epson.epsonprintsdk.EpsonService;
import com.epson.epsonprintsdk.PrinterInfo;
import com.epson.epsonprintsdk.EpsonPrintDocument;public class EpsonSdkExample {private EpsonService epsonService;public void initialize() {// 初始化服务，需在 AndroidManifest 中声明权限epsonService = new EpsonService(context);epsonService.init(context);}public void printImage(byte[] imageData, String printerName) {// 获取打印机列表epsonService.getPrinterList(new EpsonService.GetPrinterListListener() {@Overridepublic void onGetPrinterListResult(PrinterInfo[] printerInfos, int resultCode) {if (resultCode == EpsonService.SUCCESS) {for (PrinterInfo info : printerInfos) {if (info.getPrinterName().equals(printerName)) {// 构建打印文档EpsonPrintDocument document = new EpsonPrintDocument(imageData, EpsonPrintDocument.TYPE_IMAGE);// 设置打印参数EpsonPrintDocument.PrinterSetting setting = new EpsonPrintDocument.PrinterSetting();setting.setPaperSize(EpsonPrintDocument.PaperSize.A4);// 执行打印epsonService.print(document, setting, new EpsonService.PrintListener() {@Overridepublic void onPrintResult(int resultCode) {if (resultCode == EpsonService.SUCCESS) {// 打印成功}}});break;}}}}});}
}

逐行解析： EpsonService 是核心单例，负责网络通信。 getPrinterList 是异步回调，需处理线程切换，避免 UI 卡顿。 EpsonPrintDocument 封装了数据和类型，支持图片、PDF、文本。 API 变动点：Epson SDK 2.0 后，回调接口从 Listener 改为 Callback，且移除了部分同步方法。权限陷阱：需在 AndroidManifest.xml 中声明 INTERNET 和 ACCESS_NETWORK_STATE，否则静默失败。

3. Bluetooth Socket 直连实现

import java.io.OutputStream;
import java.io.IOException;
import android.bluetooth.BluetoothSocket;
import android.bluetooth.BluetoothDevice;public class BluetoothDirectExample {private BluetoothSocket socket;private OutputStream outputStream;public void connect(BluetoothDevice device) {try {// 创建 SPP 套接字socket = device.createRfcommSocketToServiceRecord(java.util.UUID.fromString("00001101-0000-1000-8000-00805F9B34FB"));socket.connect();outputStream = socket.getOutputStream();} catch (IOException e) {e.printStackTrace();}}public void sendEscPosCommand(String text) {try {// 初始化打印机outputStream.write(0x1B);outputStream.write(0x40);// 设置字体大小outputStream.write(0x1B);outputStream.write(0x21);outputStream.write(0x00);// 发送文本byte[] textBytes = text.getBytes("US-ASCII");outputStream.write(textBytes);// 换行outputStream.write(0x0A);// 打印并走纸outputStream.write(0x1B);outputStream.write(0x56);outputStream.write(0x00);outputStream.flush();} catch (IOException e) {e.printStackTrace();}}
}

逐行解析： createRfcommSocketToServiceRecord 使用 SPP 协议 UUID，这是蓝牙打印机的标准服务。 connect() 是阻塞操作，必须在子线程执行，否则 ANR。 sendEscPosCommand 发送的是 ESC/POS 指令集，这是热敏打印机的通用协议。 API 变动点：Android 12 后，BLUETOOTH_CONNECT 权限需在运行时请求，且需 neverForLocation 属性。调试技巧：使用 adb logcat -s BluetoothSocket 查看连接日志，或用 Wireshark 抓包分析指令流。

适用场景：对症下药不踩坑

场景一：通用文档打印 (A4/Letter) 选 Android 原生 API。适合办公场景，支持 PDF、Word 转换。优势是系统级支持，无需额外权限，用户体验一致。劣势是开发复杂，需处理文档转换和分页逻辑。适用人群：企业级应用，需要支持多品牌打印机的开发者。

场景二：特定品牌小票/标签打印 选 厂商 SDK。适合零售、物流行业，绑定 Epson、Zebra 等品牌。优势是功能丰富，支持切刀、二维码生成等高级功能。劣势是体积大，启动慢，跨品牌无法使用。适用人群：垂直行业应用，对打印精度和速度有极致要求。

场景三：极客定制/老旧设备兼容 选 Bluetooth Socket 直连。适合定制硬件、IoT 设备，或兼容不支持 Wi-Fi 的老打印机。优势是灵活度最高，可发送任意指令，无品牌限制。劣势是开发难度大，需熟悉协议，权限处理复杂。适用人群：硬件开发者，嵌入式工程师，追求极致控制权的极客。

避坑指南：

权限申请时机：不要在 onCreate 中申请蓝牙权限，应在用户点击“连接”按钮时申请，避免触发系统拦截。
线程处理：所有网络、蓝牙、文件 IO 操作必须在子线程，UI 更新必须在主线程，否则崩溃。
版本兼容：使用 Build.VERSION.SDK_INT 判断系统版本，针对不同版本调用不同 API。
异常处理：蓝牙连接不稳定，需实现重连机制，SDK 调用需处理网络超时。

选型建议：新手如何起步

如果你是初学者，建议从 Android 原生 API 入手。虽然代码复杂，但能深入理解系统底层，利于技术成长。参考 GitHub 开源仓库 android-printer-demo，里面有完整的权限处理和文档转换示例。该仓库由 Google 官方维护，代码规范，注释详细，是学习的好素材。

如果你的项目周期短，且绑定特定品牌，选 厂商 SDK。阅读官方文档，注意版本兼容性，避免使用已废弃的方法。 Epson 和 Zebra 的文档更新及时，社区活跃，遇到问题易解决。

如果你追求极致性能，或需要兼容老旧设备，选 Bluetooth Socket 直连。需先熟悉 ESC/POS 协议，参考《ESC/POS Programming Manual》。调试时使用串口工具，模拟指令发送，逐步排查问题。

最终建议：