简介这份资源面向Android开发初学者与需要快速集成扫码功能的工程师聚焦在Android平台上使用ZXing库完成条形码与二维码的识别和生成。ZXing作为开源条码处理方案核心由Core库与Android-Intents库组成前者负责编解码算法后者提供相机调用与扫描界面接口可覆盖从基础扫码到自定义扫描视图、二维码生成等常见需求。资源包共390个文件以201个class与176个java源码为主另含少量xml布局、png图片及apk、dex等可运行产物整体约1.01MB便于直接查阅类结构与实现细节。目前已有684人学习下载。读者可从中获取ZXing核心类如BitMatrixParser、Encoder、MultiFormatWriter的源码参考理解IntentIntegrator启动扫描、onActivityResult接收结果、权限请求与错误处理等关键环节并借鉴自定义扫描视图与性能优化的实现思路适合作为Android扫码功能开发的对照与排错参考。1. 扫码功能从零落地为什么我最终选了 ZXing 而不是 ML Kit去年接手一个仓储盘点 App需求很明确扫商品条码和二维码离线可用低端机也要跑得动。当时第一反应是用 Google 的 ML Kit毕竟官方背书、API 简洁。但真机一测就翻车了——某品牌千元机上冷启动要等两秒多而且必须依赖 Google Play 服务部分定制 ROM 直接罢工。后来换回 ZXing包体小、纯 Java 实现、不挑设备虽然 API 没那么“现代”但胜在可控。ZXingZebra Crossing是一个老牌开源条码处理库支持 QR Code、Code 128、EAN-13、Data Matrix 等主流格式。在 Android 上用它有两种姿势一是直接引入com.google.zxing:core自己写解码逻辑二是用社区封装的journeyapps:zxing-android-embedded快速集成。前者灵活但工作量大后者开箱即用但定制性差。这篇文章会从选型理由讲到完整实现再到参数调优和踩坑记录适合正在做扫码功能、被识别率和兼容性折磨的 Android 开发者。读完你能拿到一套可复现的集成方案知道每个参数改了会怎样以及哪些坑我替你踩过了。2. ZXing 核心解码链路从相机帧到条码字符串2.1 为什么不用 ML Kit三个维度的选型对比选型这件事没有绝对答案但有几个硬指标值得摆出来比。我把当时评估的三个方案列了个表维度ZXing (core)ZXing EmbeddedML Kit包体积增量~500KB~1.2MB~3MB离线能力完全离线完全离线首次需下载模型低端机帧率可调最低 5fps 可用默认 15fps依赖硬件加速自定义解码区域支持有限支持不支持依赖 Google 服务否否是关键结论如果你的 App 要覆盖大量低端机、定制 ROM或者对包体积敏感ZXing core 是更稳的选择。ML Kit 的优势在于识别速度和对模糊图像的鲁棒性但代价是包体和环境依赖。ZXing Embedded 适合快速出活但它的CaptureActivity是封装好的想改扫描框样式、解码区域、连续扫描逻辑时会很别扭。我最终选了 ZXing core 自己搭原因就一个仓储场景需要在画面中央划定一个固定区域解码避免货架远处条码误触发。这个需求 Embedded 做起来很痛苦。2.2 解码主链路PlanarYUVLuminanceSource 到 ResultZXing 的解码流程可以拆成四步相机预览回调拿到byte[]格式的 NV21 数据裁剪出感兴趣区域ROI构造PlanarYUVLuminanceSource用HybridBinarizer做二值化生成BinaryBitmap交给MultiFormatReader解码返回Result核心代码大概长这样// 相机预览回调中调用data 是 NV21 格式 public Result decodeFrame(byte[] data, int width, int height, Rect roi) { // 裁剪 ROI 区域减少计算量 PlanarYUVLuminanceSource source new PlanarYUVLuminanceSource( data, width, height, roi.left, roi.top, roi.width(), roi.height(), false // 不旋转 ); // HybridBinarizer 对光照不均的场景更友好 BinaryBitmap bitmap new BinaryBitmap(new HybridBinarizer(source)); MultiFormatReader reader new MultiFormatReader(); // 只启用需要的格式减少无效尝试 MapDecodeHintType, Object hints new EnumMap(DecodeHintType.class); hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128, BarcodeFormat.EAN_13 )); hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); reader.setHints(hints); try { return reader.decodeWithState(bitmap); } catch (NotFoundException e) { return null; // 当前帧没识别到正常情况 } finally { reader.reset(); } }几个参数值得展开说。PlanarYUVLuminanceSource的最后一个参数false表示不旋转数据如果你的相机预览是横屏但 Activity 是竖屏这里传true会多一次内存拷贝帧率会掉。HybridBinarizer比GlobalHistogramBinarizer慢一点但对反光、阴影场景的识别率高不少仓储环境光线复杂我选了前者。TRY_HARDER会让解码器尝试更多旋转角度和采样方式代价是单帧耗时增加约 30%建议只在连续几帧失败后再开启而不是一直开着。decodeWithState和decode的区别在于前者会复用内部状态连续调用时更快但每次必须reset()否则可能拿到上一帧的残留数据。这个坑我在调试时遇到过——偶尔扫出来的条码是上一次的排查了半天才发现是没 reset。2.3 相机参数配置预览尺寸与对焦模式相机配置直接决定识别率。很多教程只贴代码不说为什么这里把关键参数讲清楚Camera.Parameters params camera.getParameters(); // 选择接近 1280x720 的预览尺寸太大处理慢太小条码细节丢失 ListCamera.Size sizes params.getSupportedPreviewSizes(); Camera.Size optimal getOptimalSize(sizes, 1280, 720); params.setPreviewSize(optimal.width, optimal.height); // 连续对焦扫码场景必须开 params.setFocusMode(Camera.Parameters.FOCUS_MODE_CONTINUOUS_PICTURE); // 关闭闪光灯自动模式避免反光干扰 params.setFlashMode(Camera.Parameters.FLASH_MODE_OFF); camera.setParameters(params);预览尺寸的选择逻辑是在支持列表里找不超过 1280x720 的最大尺寸。为什么不是越大越好因为每帧数据量大了之后PlanarYUVLuminanceSource的构造和HybridBinarizer的二值化都会变慢低端机上可能从 15fps 掉到 5fps反而影响体验。1280x720 是个平衡点条码在画面中占 1/4 宽度时解码成功率已经很高。对焦模式必须用FOCUS_MODE_CONTINUOUS_PICTURE不要用FOCUS_MODE_AUTO。后者需要手动调用autoFocus在连续扫码场景下会频繁触发对焦导致画面抽搐。连续对焦模式由系统自动调节体验流畅得多。部分低端机不支持连续对焦降级方案是每隔 500ms 调一次autoFocus但要在回调里判断是否正在对焦避免队列堆积。3. 完整集成步骤从 Gradle 依赖到连续扫码3.1 依赖引入与权限声明在app/build.gradle里加两行dependencies { implementation com.google.zxing:core:3.5.2 // 如果不想自己写相机逻辑可以用 embedded 库 // implementation com.journeyapps:zxing-android-embedded:4.3.0 }core库只包含编解码逻辑不含相机和 UI需要自己用Camera2或CameraAPI 实现预览。embedded库封装了CaptureActivity适合快速集成但定制性受限。我选的是core 自写相机逻辑下面步骤都基于这个方案。AndroidManifest.xml里声明权限uses-permission android:nameandroid.permission.CAMERA / uses-feature android:nameandroid.hardware.camera android:requiredtrue /注意CAMERA是危险权限Android 6.0 以上需要运行时申请。另外如果 targetSdk 到了 30还要处理android:exported属性否则安装会报错。3.2 相机预览与解码线程分离相机预览回调onPreviewFrame运行在主线程如果直接在里面做解码UI 会卡死。正确做法是把数据丢到子线程处理// 预览回调 Override public void onPreviewFrame(byte[] data, Camera camera) { if (isDecoding.getAndSet(true)) { // 上一帧还在解码丢弃当前帧 camera.addCallbackBuffer(data); return; } // 拷贝数据到子线程避免相机复用 buffer byte[] copy Arrays.copyOf(data, data.length); decodeExecutor.execute(() - { Result result decodeFrame(copy, previewWidth, previewHeight, roiRect); if (result ! null) { mainHandler.post(() - onBarcodeDetected(result.getText())); } isDecoding.set(false); camera.addCallbackBuffer(copy); }); }这里有个关键点isDecoding原子布尔量用来做背压控制。如果解码速度跟不上帧率不加这个判断会导致任务队列无限增长内存暴涨然后 OOM。我一开始没加跑十分钟后 App 直接闪退日志里全是OutOfMemoryError。另一个坑是addCallbackBuffer。如果相机设置了预览回调 buffer每次处理完必须把 buffer 还回去否则相机不再回调新帧。用Arrays.copyOf拷贝一份数据是为了让 buffer 能尽早归还代价是多一次内存拷贝但换来了更高的帧率。3.3 连续扫码与去重逻辑仓储盘点需要连续扫多个条码不能扫一个就停。但同一个条码在画面里停留时会连续触发需要去重private final MapString, Long recentScans new ConcurrentHashMap(); private static final long DEDUP_INTERVAL_MS 2000; private boolean shouldAccept(String barcode) { long now System.currentTimeMillis(); Long lastTime recentScans.get(barcode); if (lastTime ! null now - lastTime DEDUP_INTERVAL_MS) { return false; // 2 秒内重复忽略 } recentScans.put(barcode, now); // 清理过期记录避免 Map 无限增长 recentScans.entrySet().removeIf(e - now - e.getValue() DEDUP_INTERVAL_MS * 5); return true; }去重间隔设 2 秒是个经验值。太短了同一个条码会重复录入太长了连续扫两个相同条码比如两个相同商品时第二个会被误过滤。如果业务上确实需要扫相同条码可以在 UI 上给个“强制录入”按钮点击后清空recentScans。recentScans用ConcurrentHashMap是因为解码在子线程、去重判断也在子线程但清理逻辑可能被主线程触发用并发容器省去加锁的麻烦。removeIf那行是防止 Map 无限增长虽然条码种类有限但长期运行的 App 还是加上稳妥。4. 避坑与排查识别率低、闪退、兼容性问题的血泪记录4.1 现象某些手机预览画面拉伸变形原因相机预览尺寸和 SurfaceView 的宽高比不一致系统默认拉伸填充。比如预览是 1280x72016:9但 SurfaceView 是 4:3画面就扁了。解决在surfaceChanged里根据预览尺寸和控件尺寸计算合适的布局参数用FrameLayout包裹SurfaceView并动态调整宽高。或者简单点把 SurfaceView 的layout_width/height设成match_parent然后在onMeasure里按预览比例修正。我一般会在相机初始化后拿到预览尺寸再回调给 UI 层调整。4.2 现象低端机上扫码几秒后画面卡死原因解码线程池用了无界队列帧数据堆积导致内存耗尽。或者addCallbackBuffer没正确归还相机停止回调。解决线程池用ThreadPoolExecutor并设置ArrayBlockingQueue(1)队列满了直接丢弃新帧。同时确保每条路径解码成功、失败、异常都调用了addCallbackBuffer。我后来加了个监控如果连续 30 帧没有回调就重启相机预览。4.3 现象反光或暗光环境下识别率骤降原因默认的GlobalHistogramBinarizer对光照不均处理不好或者相机曝光补偿没开。解决换HybridBinarizer并在相机参数里开启曝光补偿params.setExposureCompensation(params.getMaxExposureCompensation() / 2);另外可以在 UI 上加一个手电筒开关暗光时手动补光。注意FLASH_MODE_TORCH和FLASH_MODE_ON的区别前者是常亮后者是拍照瞬间亮扫码用TORCH。4.4 现象部分机型报Camera.open返回 null原因相机被其他 App 占用或者权限没授予或者设备本身没有后置相机。解决Camera.open前先检查getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA_ANY)用 try-catch 包裹并给用户友好提示。如果是被占用提示用户关闭其他相机应用后重试。这个在定制 ROM 上尤其常见有些系统相机进程会一直持有相机资源。4.5 现象扫出来的中文乱码原因ZXing 默认用 ISO-8859-1 解码中文条码需要指定字符集。解决在 hints 里加DecodeHintType.CHARACTER_SEThints.put(DecodeHintType.CHARACTER_SET, UTF-8);但要注意不是所有条码都按 UTF-8 编码。如果扫出来还是乱码可以尝试GBK。更稳妥的做法是先按默认解拿到结果后判断是否包含乱码字符再尝试其他编码重新解。不过重新解需要保留原始BinaryBitmap不能reset掉。5. 进阶技巧ROI 动态调整与解码性能量化5.1 动态 ROI根据条码位置自适应裁剪固定 ROI 在大多数场景够用但如果条码不在画面中央用户需要移动手机去对准体验不好。进阶做法是先全画面低分辨率扫描检测到条码大致位置后再缩小 ROI 精细解码。ZXing 本身不提供条码检测功能但可以用GenericMultipleBarcodeReader做多区域尝试GenericMultipleBarcodeReader multiReader new GenericMultipleBarcodeReader(reader); Result[] results multiReader.decodeMultiple(bitmap, hints);这个类会把画面切成多个子区域分别解码适合一次扫多个条码的场景。代价是耗时成倍增加建议只在用户点击“多码扫描”按钮时启用日常扫码还是用单区域。5.2 解码耗时量化用 System.nanoTime 定位瓶颈优化不能靠感觉得量化。我在decodeFrame里加了耗时统计long t0 System.nanoTime(); PlanarYUVLuminanceSource source new PlanarYUVLuminanceSource(...); long t1 System.nanoTime(); BinaryBitmap bitmap new BinaryBitmap(new HybridBinarizer(source)); long t2 System.nanoTime(); Result result reader.decodeWithState(bitmap); long t3 System.nanoTime(); Log.d(ZXing, String.format(source%dms binarize%dms decode%dms, (t1-t0)/1000000, (t2-t1)/1000000, (t3-t2)/1000000));实测数据某千元机1280x720 ROI 640x480PlanarYUVLuminanceSource构造约 2msHybridBinarizer约 8msdecodeWithState约 15ms。瓶颈在解码本身所以减少POSSIBLE_FORMATS数量、关闭TRY_HARDER是最有效的优化手段。如果只扫 QR Code把格式限制为一种解码能降到 8ms 左右。5.3 一个容易忽略的细节相机预览格式CameraAPI 默认预览格式是 NV21PlanarYUVLuminanceSource正好接受 NV21。但有些设备默认是 YV12直接传进去会花屏。保险做法是显式设置params.setPreviewFormat(ImageFormat.NV21);如果设备不支持 NV21极少见需要自己做 YV12 到 NV21 的转换网上有现成工具类。这个坑我在某国产平板上遇到过排查了一下午才发现是格式不匹配。从那以后我每次集成扫码功能都会先在目标机型上跑一遍耗时统计和格式检查确认 ROI 尺寸、预览格式、对焦模式这三个参数没问题再往下写业务逻辑。这套流程帮我省了不少返工时间。希望帮到你。本文还有配套的精品资源点击获取