手机连打印机保姆级教程：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》。
调试时使用串口工具，模拟指令发送，逐步排查问题。
最终建议：企业级应用：原生 API + 自定义 Adapter
垂直行业：厂商 SDK
硬件定制：直连方案技术选型没有绝对的好坏，只有适合与否。
明确你的业务场景、目标用户、维护成本，再决定路线。
记住，代码不是写给自己看的，是写给未来维护的人看的。
清晰、简洁、可测试，比炫技更重要。
结尾互动
手机连打印机的技术栈还在快速迭代，蓝牙 5.0、Wi-Fi Direct 等新特性不断涌现。
你在项目中遇到过哪些权限坑？或者 API 变更导致的崩溃？
还有什么不懂的？评论区留言挨个回。
分享你的踩坑经验，帮后来者少走弯路。
点赞收藏，下次开发不迷路。 手机连打印机保姆级教程：3步搞定API变更痛点
手机连打印机保姆级教程：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》。
调试时使用串口工具，模拟指令发送，逐步排查问题。
最终建议：企业级应用：原生 API + 自定义 Adapter
垂直行业：厂商 SDK
硬件定制：直连方案技术选型没有绝对的好坏，只有适合与否。
明确你的业务场景、目标用户、维护成本，再决定路线。
记住，代码不是写给自己看的，是写给未来维护的人看的。
清晰、简洁、可测试，比炫技更重要。
结尾互动
手机连打印机的技术栈还在快速迭代，蓝牙 5.0、Wi-Fi Direct 等新特性不断涌现。
你在项目中遇到过哪些权限坑？或者 API 变更导致的崩溃？
还有什么不懂的？评论区留言挨个回。
分享你的踩坑经验，帮后来者少走弯路。
点赞收藏，下次开发不迷路。