简介一套面向 Android 开发者的二维码与条形码扫描功能实践资料基于 ZXing 开源库完整覆盖依赖接入、扫描界面定制、相机权限处理与扫描结果回调等关键环节适合需要快速集成扫码能力或做二次开发的移动应用工程师。压缩包共 1874 个文件整体约 18.42MB以 Java 源码、XML 布局、Gradle 工程配置、Jar 依赖及 dex/class 编译产物为主同时包含可直接运行体验的 APK 和使用说明 docx。目前已有 2535 人学习下载。附带的 MyApplication 示例工程与说明文档可对照学习能从零跑通 ZXing 集成流程理解自定义扫描界面、闪光灯控制、扫描区域指示及常见异常处理兼具教学与工程参考价值。1. 扫码功能选型为什么是 ZXing core 而不是整套 SDK做盘点类的模拟项目X时我需要在一个安卓端应用里同时扫二维码和商品条码扫码框还得嵌到自研 UI 里不能用一个固定样式的页面。考察了一圈现成的扫码 SDK要么包体太大要么扫码框样式写死要么对一维码的支持很敷衍最后我决定只用 ZXing 的 core 库把相机预览、对焦、解码循环全部自己写。ZXing 是业内最老牌的开源解码库离线可用同时覆盖二维码和 CODE_128、EAN-13 等一维码适合想把扫码功能做轻、做可控的安卓开发者。这套方案不依赖任何扫码页面资源几百行代码就能落地所有 Camera 参数都裸露在外面遇到问题可以直接查相机栈而不是在黑匣子里猜。真机调试时最棘手的其实是三件事预览画面、扫码框、解码区域三者经常对不上小票条码和反色码识别率惨不忍睹部分机型在弱光下对焦拉风箱。这些我会在后面的章节按踩坑记录展开。如果你正在评估扫码方案或者手上有个扫码模块想重构这篇笔记应该能省你几天时间。2. 库的接入与解码参数只用 core不碰全家桶2.1 为什么不用 zxing-android-embeddedzxing-android-embedded 是社区封装好的完整扫码模块里面带了相机管理、扫码 Activity、布局文件和提示音接入后确实能快速跑起来。但我在一维码场景里吃过亏嵌入式库把相机封装得太深我想对 Camera 做一点“魔改”——比如设置缩放、切换连续对焦、开辅助补光、处理反色码——要么走反射要么升级一次库就把代码打回原样。ZXing core 则是纯 Java 的解码算法库不包含任何 Android UI 依赖。相机的打开、预览回调、解码线程、扫码框绘制全由自己掌控。代价是多写几百行胶水代码换来的是每个参数都可调、每个异常都可见。如果你是那种喜欢把问题定位到具体一行的开发者core 方案明显比全家桶舒服。2.2 添加依赖、权限与工程配置在模块的 build.gradle 里加一行依赖即可核心库本身非常轻dependencies { implementation com.google.zxing:core:3.5.3 }然后 AndroidManifest 里声明相机和振动权限uses-permission android:nameandroid.permission.CAMERA / uses-permission android:nameandroid.permission.VIBRATE / uses-feature android:nameandroid.hardware.camera android:requiredfalse /这里提三个容易忽略的点。第一core 是纯 Java 库理论上任何 Android 版本都能用但注意不要和项目里其他 SDK 传递依赖进来的旧版 zxing 冲突我现在统一锁定 3.5.3。第二VIBRATE 权限是给“扫码成功震动反馈”用的如果你不想要震动可以不声明。第三Android 6.0 以后 CAMERA 属于运行时权限在进入扫码页之前要单独请求不能在 Manifest 里写完就当没事。2.3 解码器配置核心类与 Hint 参数ZXing 的解码入口是 MultiFormatReader它可以根据你设置的 Hint 组合在多种码制之间自动选择和尝试。我的初始化代码一般长这样MultiFormatReader reader new MultiFormatReader(); MapDecodeHintType, Object hints new EnumMap(DecodeHintType.class); hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128, BarcodeFormat.CODE_39, BarcodeFormat.EAN_13, BarcodeFormat.UPC_A, BarcodeFormat.UPC_E)); hints.put(DecodeHintType.CHARACTER_SET, UTF-8); reader.setHints(hints);这段配置里TRY_HARDER 会牺牲一点点速度换取对小角度倾斜、模糊码的识别提升扫码场景里我一般都会开。POSSIBLE_FORMATS 用来收紧格式范围只保留你业务里真正需要的码制否则识别时会在每种格式上做尝试速度慢而且容易出现误识别。CHARACTER_SET 对含中文的二维码内容很关键不设 UTF-8 时可能拿到乱码。解码管线上的核心类大概就四个弄清楚它们的分工后面调参才有方向。类职责PlanarYUVLuminanceSource把相机 NV21 帧包装成可裁剪的亮度矩阵HybridBinarizer局部阈值二值化抗光照不均GlobalHistogramBinarizer全局直方图二值化细线条场景下有时更稳MultiFormatReader多格式解码器按 Hint 尝试并返回 Result二值化这个环节值得一提HybridBinarizer 在暗光、渐变光场景下明显更稳默认用它没问题。但如果你发现某些细线条的一维码在强光下反复失败可以试试 GlobalHistogramBinarizer它按全局亮度分布切分对高对比度条码偶尔有奇效。两套二值化器切换只需要换一行构造参数遇到玄学识别问题时值得作为一个排查项。3. 相机帧到二维码结果从预览到出码的完整实现3.1 预览回调与相机生命周期管理相机这块最核心的教训是一切操作必须等 Surface 真正创建之后再执行。我见过太多黑屏问题本质都是在 surfaceCreated 之前就调用了 setPreviewDisplay 或者 startPreview。正确骨架如下public class CameraPreview implements SurfaceHolder.Callback { private Camera camera; private PreviewCallback previewCallback; Override public void surfaceCreated(SurfaceHolder holder) { openCameraSafely(); if (camera ! null) { camera.setDisplayOrientation(getPreviewDegree()); try { camera.setPreviewDisplay(holder); } catch (IOException e) { releaseCamera(); } } } Override public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) { if (camera null) return; // 先停掉旧预览再重新配置参数否则部分机型会出现首帧黑屏 camera.stopPreview(); configureCameraParams(width, height); camera.setPreviewCallbackWithBuffer(previewCallback); camera.addCallbackBuffer(createPreviewBuffer(width, height)); camera.startPreview(); } }每次配置参数之前先 stopPreview这是血泪经验。有些设备不停止预览直接 setParameters要么不生效要么出现画面撕裂。createPreviewBuffer 分配的是 YUV420 数据缓冲区size 用width * height * 3 / 2计算NV21 格式是这个大小。buffer 放给相机之后相机每帧都会往里写数据写完通过回调还给应用具体复用逻辑放到最后一章讲。3.2 后台解码线程与帧率控制解码不能放在主线程也不能放在相机回调线程里否则预览会卡顿甚至 ANR。我习惯用一个 HandlerThread 串行处理预览帧收到帧数据后直接 post 到解码线程final class DecodeHandler extends Handler { private final MultiFormatReader reader; private final DecodeListener listener; Override public void handleMessage(Message msg) { byte[] data (byte[]) msg.obj; int width msg.arg1; int height msg.arg2; PlanarYUVLuminanceSource source new PlanarYUVLuminanceSource( data, width, height, 0, 0, width, height, false); Result result null; try { result reader.decodeWithState(new BinaryBitmap( new HybridBinarizer(source))); } catch (Exception ignored) { // 没识别到是常态不能在这里抛异常 } finally { reader.reset(); } if (result ! null) { listener.onDecoded(result); } } }这段逻辑里有两个细节值得讲。第一decodeWithState 在每帧识别结束后要调用 reset()否则内部状态会残留到下一帧导致连续出码或误码。第二每次 try 里必须把 Exception 全部吞掉因为绝大多数帧本来就是扫不出来的抛异常只会拖慢线程。帧率控制上我一般会加一个“解码中”标记如果上一帧还没解完新帧就直接丢弃宁可少解几帧也不让解码线程积压。3.3 结果回调与扫码框的坐标换算解码成功后Result 里带的是相机原始帧坐标系下的 ResultPoint 数组二维码有三个定位点一维码通常有两个端点。但屏幕上扫码框是 View 坐标系两者不能直接画等号。我的做法是先做一个通用的坐标映射PointF mapToScreen(ResultPoint p, int frameW, int frameH, int viewW, int viewH, int rotation) { // 旋转 90/270 度时宽高互换后再缩放 float scaleX viewW / (rotation % 180 0 ? (float) frameW : frameH); float scaleY viewH / (rotation % 180 0 ? (float) frameH : frameW); return new PointF(p.getX() * scaleX, p.getY() * scaleY); }这就是扫码框动画能和真实条码贴合的底层逻辑。如果你不做这一步换算最典型的表现是扫码框中心对准条码扫不出来把条码挪到框外反而能扫出。后面避坑章节会再展开一次。你可以在解码成功回调里把这四个点传给自定义 View让四个角标画到对应位置视觉效果就会像“框住了条码”。4. 条形码扫描专项一维码为什么更难参数怎么调4.1 一维码和二维码的识别差异二维码的定位图案和容错机制决定了它哪怕有 30% 面积被遮挡、或者倾斜一定角度依然能恢复出来。一维码完全不一样它的信息全部编码在水平方向的条和空的宽度序列里一旦某一根细条模糊、断裂、或者反光过曝整个解码就直接失败。维度二维码一维码信息维度二维矩阵一维条带容错能力有分级容错基本无容错对清晰度要求整体锐利即可条宽像素必须足够常见格式QR_CODECODE_128 / EAN-13误识别风险低高需限制格式实践中一个关键经验是一维码在画面中的宽度占比直接决定成功率。当条码占画面宽度小于三分之一时识别率会掉到很难看的程度占三分之二以上时成功率才比较稳定。所以一维码扫码页会主动拉近画面不是心理作用是为了让条宽在传感器上多占几个像素。4.2 解码格式限制与调参代码同时扫二维码和一维码时不能直接把所有格式都丢给 MultiFormatReader否则二维码抢在一维码前面消耗大量解码时间。我通常根据页面类型切换 hintsMapDecodeHintType, Object productHints new EnumMap(DecodeHintType.class); productHints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.CODE_128, BarcodeFormat.CODE_39, BarcodeFormat.CODE_93, BarcodeFormat.EAN_13, BarcodeFormat.EAN_8, BarcodeFormat.UPC_A, BarcodeFormat.UPC_E)); productHints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); productHints.put(DecodeHintType.ALLOWED_LENGTHS, new int[]{6, 8, 13, 14}); reader.setHints(productHints);ALLOWED_LENGTHS 是个双刃剑。EAN-13 固定 13 位、UPC-A 固定 12 位限制长度能大幅降低误识别比如画面里的随机条纹不会被误认为条码。但 CODE_128 是变长的千万别给它设长度否则超过你预设长度的合法码全会被拒掉。我踩过一次把 CODE_128 限制成长度 10结果扫码枪打出来的 14 位序列号死活扫不出排查了半天才意识到是 ALLOWED_LENGTHS 误杀。4.3 对焦模式选择与主动拉近一维码对清晰度极其敏感连续对焦是首选前置条件判断不能省Camera.Parameters params camera.getParameters(); ListString modes params.getSupportedFocusModes(); if (modes.contains(Camera.Parameters.FOCUS_MODE_CONTINUOUS_PICTURE)) { params.setFocusMode(Camera.Parameters.FOCUS_MODE_CONTINUOUS_PICTURE); } else if (modes.contains(Camera.Parameters.FOCUS_MODE_AUTO)) { params.setFocusMode(Camera.Parameters.FOCUS_MODE_AUTO); camera.autoFocus(null); }部分设备只有默认无对焦模式此时一维码基本残废只能在 UI 上提示用户拉远拉近找位置。缩放是另一个重要的辅助手段。每次进入扫码页我习惯把画面主动放大一点但不能拉满Camera.Parameters params camera.getParameters(); if (params.isZoomSupported()) { int maxZoom params.getMaxZoom(); params.setZoom((int) (maxZoom * 0.35f)); camera.setParameters(params); }放大 35% 到 40% 是我反复调出来的经验值太小对细条没有实质帮助太大容易让条码超出画面或者近距离对焦失败。请记住一个原则放大是补救手段不是万灵药。扫码页引导用户把条码放正、占满扫码框三分之二才是根本解法。5. 扫码开发里的常见问题排查五处翻车记录与解决办法5.1 黑底白码的反色码扫不出来现象白底黑字的二维码秒出黑底白字的反色码一帧都扫不出同一台设备同样的距离。原因ZXing 的二值化默认按“白纸黑字”的极性去找条码边缘黑底白字会把亮度关系完全颠倒HybridBinarizer 处理后条码区域变成一片黑或一片白边缘信息全丢。解决把亮度分量反转后再走一遍解码。NV21 帧里 Y 分量在前UV 交错在后面反色时只反 Y不要动 UV 色度分量// 只反转亮度分量色度保持原样 int yLength width * height; for (int i 0; i yLength; i) { data[i] (byte) (255 - (data[i] 0xFF)); }我一般是在原帧解码失败后再拿反色帧尝试一次。要注意这个操作必须在线程里做因为它是 O(n) 的循环主线程跑会掉帧。现在很多会员码、代金券故意做黑底或深色底如果不处理反色场景上线后一定会收到“扫不出来”的反馈。5.2 相机黑屏或预览卡在第一帧现象扫码页打开是黑屏退出重进偶尔恢复甚至有些机型第一次进能正常预览第二次进就黑。原因最常见的两个。一是 Surface 还没创建完成就调用了 setPreviewDisplay二是前一个页面没有释放 Camera 实例新页面 Camera.open() 时拿到的是 null 或直接抛异常。部分机型对 Camera 释放的时机特别敏感onPause 里没释放onResume 里就再也打不开。解决严格执行 surfaceCreated 后再 open 相机的顺序所有 open 操作包 try-catch失败时允许用户点屏幕重试onPause 里无条件 releaseCamera()并把 camera 引用置空避免下一次进入时拿到脏对象。我后来把这个流程封装成了一个状态机黑屏问题基本绝迹。5.3 小票条码识别率低现象超市小票、快递面单上的条码要对半天才能扫出经常超时自动退出。原因小票打印机的分辨率本来就不高条宽很窄再加上纸面卷曲、反光、手指遮挡一维码只要有一小段模糊整张就废。这类场景和屏幕上渲染出来的高清二维码完全不是一个难度级别。解决三条措施叠加。第一放大画面让条码占预览宽度三分之二以上。第二缩小 ROI 解码区域把解码范围限制到扫码框内部减少周围纹理对二值化的干扰。第三关闭连续对焦改用自动对焦并监听对焦完成后再启动解码避免在合焦瞬间之前一直用模糊帧做无效尝试。如果你发现条码离镜头很近时反复对不上焦可以额外尝试把对焦模式切到 MACRO部分设备在 10 厘米内确实需要微距模式。5.4 ZXing 类冲突和版本冲突现象编译报重复类或者运行时 NoSuchMethodError崩溃栈指向 zxing 包名。原因项目里某个依赖 SDK 自己带了一份很老版本的 zxing和你显式依赖的 3.5.3 里的类结构不一样。两个版本的包名完全一致Gradle 去重时只能留一个留了旧的就会出现 NoSuchMethodError。解决先定位是谁带来的传递依赖然后显式排除implementation(com.google.zxing:core:3.5.3) { // 排查后确定是别的 SDK 带来的旧版 zxing整包排除 }更彻底一点的做法是全局排除所有传递依赖里的 zxing只保留自己声明的那份configurations.all { exclude group: com.google.zxing }这个操作要放在顶层 build.gradle 里加之前先确认没有其他模块直接依赖了旧版。这个坑最大的麻烦在于它不是必现的换一个依赖版本可能就冒出来建议在集成扫码功能时就把排除规则写好。5.5 扫码框显示与解码区域错位现象扫码框对准条码中心怎么都扫不出把条码放到框外反而秒出扫码动画指示的那条线完全失真。原因相机原始帧是横向传感器数据预览显示经过旋转、缩放后投射到屏幕扫码框是屏幕 View 坐标系。如果直接用扫码框的 View 坐标去裁剪 YUV 数据必然错位。我最早犯的错就是直接在data上按 View 的 left/top 去切结果扫到的区域完全不是用户看到的位置。解决做坐标映射。核心是算出两个坐标系之间的缩放比旋转 90 度时宽和高的映射要互换float scaleX cameraFrameWidth / (float) previewView.getWidth(); float scaleY cameraFrameHeight / (float) previewView.getHeight(); int frameLeft (int) (viewRect.left * scaleX); int frameTop (int) (viewRect.top * scaleY); int frameRight (int) (viewRect.right * scaleX); int frameBottom (int) (viewRect.bottom * scaleY);如果你的预览方向是 90 度或 270 度还需要把 scaleX 和 scaleY 互换见第三章的 mapToScreen这里不再重复。排查这个问题的诀窍是在解码线程里把要裁剪的区域写到一个日志里再用截图工具对比实际画面一两轮就能看出偏移规律。6. 把识别率再冲一冲帧缓冲复用与 ROI 裁剪技巧6.1 用 setPreviewCallbackWithBuffer 减少 GC 和帧抖动默认的 setPreviewCallback 每帧回调都会新建一个 byte[]在 30fps 下意味着每秒要产生 30 个大数组内存抖动比你想的严重得多。我的做法是交给相机一块固定缓冲区让它循环填、循环用Override public void onPreviewFrame(byte[] data, Camera camera) { // 带标记上一帧还没解完就跳过避免积压 if (isDecoding.compareAndSet(false, true)) { decodeHandler.post(() - { decodeAndNotify(data); isDecoding.set(false); }); } // 复用的是同一块 buffer不会新增内存 camera.addCallbackBuffer(data); }配合解码线程的“正在解码”标记这套组合让我把扫码页的掉帧率压到了很低的水平。初始化时只需要在 surfaceChanged 里分配一次camera.setPreviewCallbackWithBuffer(previewCallback); camera.addCallbackBuffer(new byte[width * height * 3 / 2]);注意旋转屏幕或者切换摄像头后预览尺寸会变缓冲区必须重建否则会出现花屏。6.2 在 YUV 层对扫码框 ROI 做裁剪裁剪可以减少解码像素量同时避开扫码框外的高频干扰。但 NV21 裁剪有个容易踩的细节UV 分量是 2x2 像素共享一个采样点所以裁剪的 left 和 top 必须是偶数否则颜色会发生偏移。一个可靠的裁剪函数大致这样private byte[] cropNv21(byte[] src, int srcW, int srcH, int left, int top, int cropW, int cropH) { byte[] dst new byte[cropW * cropH * 3 / 2]; // Y 分量逐行拷贝 for (int row 0; row cropH; row) { System.arraycopy(src, (top row) * srcW left, dst, row * cropW, cropW); } // UV 分量行每两行 Y 对应一行 UV int srcUvOffset srcW * srcH; int dstUvOffset cropW * cropH; for (int row 0; row cropH / 2; row) { System.arraycopy(src, srcUvOffset (top / 2 row) * srcW left, dst, dstUvOffset row * cropW, cropW); } return dst; }调用时把裁剪后的 byte[] 传给 PlanarYUVLuminanceSource解码器只处理扫码框内的区域。这块做对后有两处明显收益识别成功率高了一截低端机器上的解码时延也降了不少。从那以后我每次做扫码功能都强制自己走一遍流程先测黑底反色码再测小票条码确认 Buffer 复用和 ROI 裁剪都在位。ZXing 的解码算法本身很稳真正的幺蛾子全在相机参数和坐标系换算上希望这些经验能帮到你。本文还有配套的精品资源点击获取