简介这是一份面向Android开发者的Zxing二维码扫描学习资源适合需要快速集成扫码功能或研究二维码识别原理的移动开发人员。压缩包共1172个文件大小约4.88MB包含491个flat编译资源、324个class字节码、134个xml布局与配置、118个json和68个java源码另有jar依赖、Gradle构建脚本及图片资源整体是一套结构完整的Android示例工程。已有237人学习下载。通过这份资源可对照源码理解Zxing图像预处理、灰度化与二值化、二维码定位及解码的完整流程学习QR码、Data Matrix、PDF417、UPC/EAN、Code 128等多种码制的支持方式。工程内还提供了实时摄像头扫描与离线图片识别示例AndroidManifest、资源文件和Gradle配置等内容可帮助开发者自定义扫描界面、配置解码参数并为集成到实际App提供可直接套用的工程范式。1. 二维码扫描Zxing它不是扫码App是需自己组装的解码引擎说起二维码扫描Zxing英文名一般写作 ZXing很多同学第一反应是「开源扫码库拿来集成」。真到项目里才发现它给你的不是「扫码界面 一声滴」而是一套可以塞进 Java/Android/服务端的解码引擎输入图像或相机帧输出码里的字符串。取景框、对焦、闪光灯、解码线程调度这些「扫码体验」都要你亲自拼恰恰是这道拼装功夫决定了你是「快准稳」还是「时好时坏」。我会沿着三条线讲搞懂 ZXing 的模块边界把「生成二维码」和「实时扫码」两条路用最小代码跑通把扫码率上不去的常见坑排查掉。适合准备自研扫码组件、被某全家桶 SDK 体积劝退、以及正在为扫码问题失眠的开发者。我自己调扫码时也被这些问题卡过后面写的每一条都有对应翻车现场。2. 拆解ZXing能力边界core、javase 与 android 模块各管什么ZXing 的仓库按运行环境拆成了好几个模块绝大多数业务只需要依赖「core」。它不依赖 Android不依赖 AWT纯 Java 实现了解码、生成两条主链路。javase 模块是桌面/服务端的辅助壳提供 BufferedImage、Swing 之类的适配android 模块则是官方当年的相机示例。搞清这个边界依赖就不会乱排查问题时也知道去哪里找类。2.1 解码管线先从像素里抽出亮度再变成黑白位图不管入口是相机帧还是 PNG 图片ZXing 都走同样的管线。第一步把图像变成 LuminanceSource 亮度源第二步用 Binarizer 把亮度数组按阈值切成黑白两色得到 BinaryBitmap第三步让 Reader 在黑白位图里找定位图形、解析模块序列。所以 LuminanceSource 不是某个具体文件格式而是「像素怎么排列」的抽象这也是 core 不碰任何 UI 框架就能跨平台工作的原因。二值化器是扫码率的第一黑匣子。默认 HybridBinarizer 会按局部区域算阈值渐变阴影、光照不均时比 GlobalHistogramBinarizer 稳Global 快但只适合对比度极好的干净码图。实时扫码我一般用 Hybrid桌面批量处理如果图像是程序生成的用 Global 能省一点时间。Reader 端的参数集中在 DecodeHintType常见配置可以写成MapDecodeHintType, Object hints new HashMap(); // TRY_HARDER 会额外尝试旋转和更细的采样实时场景慎开 hints.put(DecodeHintType.TRY_HARDER, Boolean.FALSE); // 只声明需要的码制声明越多单帧耗时越多 hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList(BarcodeFormat.QR_CODE, BarcodeFormat.DATA_MATRIX)); // 中文内容必须显式声明 UTF-8否则字节模式按 ISO-8859-1 走 hints.put(DecodeHintType.CHARACTER_SET, UTF-8); reader.setHints(hints);代码逻辑说明setHints 只需调用一次频繁调用会触发内部状态重建。TRY_HARDER 打开后单帧解码耗时可能翻倍适合扫很小或残缺的码实时取流场景默认关掉更理性。POSSIBLE_FORMATS 列表越长MultiFormatReader 每次尝试的 Reader 越多这里只声明 QR 和 DataMatrix解码速度会明显好于不设这个参数。CHARACTER_SET 影响带中文的二维码在字节模式下的解码映射历史坑非常多。2.2 javase 模块桌面批量解析用一张 BufferedImage 跑通服务端要批量解析一批图片时javase 模块的 ImageIO 适配最省事。我一般只在 pom 或 gradle 里加 core 和 javase 两个坐标不引入任何相机或 UI 依赖解析代码直接读文件BufferedImage image ImageIO.read(new File(/data/qr_codes/qr.png)); // 一次性取出全像素 ARGB 数组避免逐像素 getRGB 的巨大开销 int[] pixels image.getRGB(0, 0, image.getWidth(), image.getHeight(), null, 0, image.getWidth()); RGBLuminanceSource source new RGBLuminanceSource( image.getWidth(), image.getHeight(), pixels); BinaryBitmap bitmap new BinaryBitmap(new HybridBinarizer(source)); Result result new MultiFormatReader().decode(bitmap); System.out.println(result.getText());这段代码的要点是getRGB 一次性拿全像素如果你写成双层 for 循环逐点 getRGB一张 1920×1080 的图会慢到怀疑人生。RGBLuminanceSource 的宽高必须与像素数组一一对应第二趟参数用了 image.getWidth() 作为 stride换行时数组索引才不错位。另一个容易翻车的地方是图片本身可能带了方向信息桌面环境里 EXIF 旋转不会自动应用批量解析前最好用工具把方向先固定。用 javase 模块做批量解析时同一个 MultiFormatReader 实例可以反复 decode不需要每次 new但它在一次 decode 失败后会保留内部状态连续解析异常时记得调用 reset()否则某些状态会导致后续帧匹配错乱。这个小习惯能避开一批莫名其妙的问题。2.3 android 模块的老代码思路值得抄依赖不建议引android 模块里有 CameraManager、ViewfinderView 这些类是官方当年基于 Camera API 写的扫码示例。它把自动对焦、预览帧裁剪、取景框画线都做全了你的确能改一改就跑起来。问题在于它捆绑了旧的 Camera API 和一套 Activity 结构类名设计也是围绕示例场景和现在主流 CameraX、SurfaceView 自绘的方案耦合很差。依赖它往往带来一堆不需要的权限声明和生命周期代码改动成本比重新写还高。我的习惯是只参考 android 模块的算法选取怎么把预览帧切成中央矩形、怎么用 PlanarYUVLuminanceSource 直接吃 NV21 数据、反色码为什么需要 InvertedLuminanceSource。这些思路在后面两章会逐步落到代码里。生产项目里依赖树只保留 core 一个坐标扫码界面全部自己写这样才能控制预览、线程和权限。模块职责适合场景core生成、解码、码制实现无 UI 依赖所有移动端与服务端javaseBufferedImage、Swing、命令行适配桌面工具、批量解析、服务端批处理androidCamera 示例、取景框 View、老相机适配学习参考、快速原型3. 用ZXing生成二维码最小Java代码与四个必调参数需要生成码的场景比扫码还多设备标签、单据回执、小程序入口。ZXing 的 QRCodeWriter 能输出一个 BitMatrix矩阵转图片走 javase 的 ImageIO。很多人生成失败或生成后扫不出多数不是算法问题而是参数没喂对。下面给一份可直接跑的代码再讲清楚四个必调参数。3.1 最小生成代码BitMatrix 到 BufferedImage 的完整链路import com.google.zxing.BarcodeFormat; import com.google.zxing.EncodeHintType; import com.google.zxing.common.BitMatrix; import com.google.zxing.qrcode.QRCodeWriter; import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel; import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.File; import java.util.HashMap; import java.util.Map; public class QrGenerator { public static void main(String[] args) throws Exception { // 中文内容必须配 UTF-8否则字节模式下会被打成 ISO-8859-1 String content 你好ZXing这是二维码内容示例; int size 512; MapEncodeHintType, Object hints new HashMap(); hints.put(EncodeHintType.CHARACTER_SET, UTF-8); hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.M); hints.put(EncodeHintType.MARGIN, 1); QRCodeWriter writer new QRCodeWriter(); BitMatrix matrix writer.encode(content, BarcodeFormat.QR_CODE, size, size, hints); BufferedImage image new BufferedImage(size, size, BufferedImage.TYPE_INT_RGB); for (int x 0; x size; x) { for (int y 0; y size; y) { // matrix 的坐标系是列在前、行在后 image.setRGB(x, y, matrix.get(x, y) ? 0x000000 : 0xFFFFFF); } } ImageIO.write(image, png, new File(qr_hello.png)); System.out.println(生成完成); } }代码逻辑说明encode 返回的 BitMatrix 不是图片只是记录了哪些坐标是黑点。matrix.get(x, y) 的 x 是第一维、y 是第二维写循环时别按直觉写成 get(y, x)否则输出会转置。转换成 BufferedImage 时用 setRGB 逐点写但对大尺寸图片会更慢想提速就改成直接写 int 像素数组再 setRGB(0,0,w,h,pixels,0,w)。生产环境我一般用后者512×512 的差不了多少2048 以上就能感受到差距。QRCodeWriter 是线程安全的服务端可以做成单例复用。每次 new 一个 writer 本身开销不大但频繁调用的接口里复用更干净。3.2 四个必调参数字符集、容错、边距与尺寸生成时最容易踩的参数集中在这四个。size 是 encode 方法的入参其余三个是 EncodeHintType 的字典值。它们互相影响size 太小、容错太高码就会密到扫不出来。参数取值建议说明CHARACTER_SETUTF-8有中文必填QR 码字节模式默认字符集对中文不友好ERROR_CORRECTIONM 或 H普通屏幕展示用 M贴产品外壳或印在布上要 HMARGIN1单位是模块数0 会导致边缘紧贴打印或被抠图时容易失败size512 起步内容多或容错高时按倍数上调不要用 200 以下的尺寸压图CHARACTER_SET 的坑在中文场景最要命。同一段中文不设这个 hint生成端默认按 ISO-8859-1 处理部分解码器会直接抛 IOException另一部分解出来是乱码。容错级别越低码图越稀疏、越容易扫但脏污、褶皱、遮挡场景又要求高容错。我的经验是印在纸上取 H屏幕展示取 M纯数字短内容用 L 也没问题。MARGIN 这个参数经常被忽略它代表二维码四周的空白模块数。很多生成器默认把它留出来了ZXing 的 MARGIN 默认是 4你自己设置成 0 会看到码直接顶到图片边缘。打印贴纸时边缘裁切稍有偏差定位图形被切掉一角扫码率立刻崩。这个参数最不引人注意却是翻车率最高的一个。3.3 加 logo、换颜色之前的冷静判断需求方最喜欢问能不能把二维码中间放个 logo、换个品牌色。技术上可以做但 ZXing 生成的黑白矩阵是信息载体你直接在矩阵上覆盖 logo遮挡区域的数据模块就丢了。容错级别 H 能兜住一部分遮挡但不能无限制。我见过有人把 logo 做得几乎撑满半个码结果整批标签只能碰运气扫出。如果确实要加 logo我一般的做法是先按 H 容错生成再把 logo 缩到码边长的 1/5 以内居中贴上去最后打样至少扫 50 次验证。颜色上解码器只关心明暗对比深蓝、深绿这类深色当前景浅色当背景别把前景做成浅黄、背景做成深灰除非你想现场体验一把玄学扫码。生成后立刻自我验证这步很重要。任何生成逻辑改过参数我都会顺手写个单元测试生成 PNG 再走一遍 core 的 decode确认内容一致。这个测试只花几十毫秒能挡掉上面大部分参数事故。4. Android实时扫码最小实现相机帧到识别结果的管线怎么搭实时扫码的核心不是 UI而是相机帧怎么进、解码结果怎么出。ZXing 的 core 模块提供了 PlanarYUVLuminanceSource可以直接吃 Camera 预览回调里的 YUV 数据完全不用先转 Bitmap。这一章给一套最小可跑的管线包含预览帧处理与反色兜底。4.1 不转 Bitmap 的数据通路PlanarYUVLuminanceSource 直接吃 YUVAndroid Camera 的 onPreviewFrame 回调给的是 YUV 格式的 byte[]常见是 NV21。老式写法里有人先 YUV→Bitmap→RGBLuminanceSource中间多两次全图转换帧率直接掉一半。ZXing 专门为这种场景写了 PlanarYUVLuminanceSource构造函数里指定数据、宽高和裁剪区域它在内部直接从 Y 平面取亮度不需要颜色转换。这里有个容易错的地方宽高必须传相机预览的实际尺寸不是屏幕尺寸。预览 1920×1080解码也按这个尺寸走如果你嫌大可以只传核心区域比如中央 600×600 的矩形。拿屏幕尺寸去构造亮度数组的偏移全错结果是永远扫不出且不报错排查起来极像没有规律。// data 来自 onPreviewFramewidth/height 为相机预览尺寸 PlanarYUVLuminanceSource source new PlanarYUVLuminanceSource( data, // NV21 数据 width, height, // 预览宽高 0, 0, // 裁剪区域左上角 width, height, // 裁剪区域宽高这里是全帧 false); // 是否横竖屏反转相机数据通常为横 BinaryBitmap binary new BinaryBitmap(new HybridBinarizer(source));逻辑说明构造参数里最后那个 boolean 表示数据是否已经做了 90 度旋转Camera 预览回调默认是横向传感器竖屏界面看到的画面是 UI 层旋转后的但解码数据仍然是横的。绝大多数场景传 false 就行解码结果的条码方向交给 TRY_HARDER 或旋转尝试处理。4.2 最小解码线程一个解不出来就换下一帧把解码放到相机回调线程里是新手最容易犯的错。一次解析在复杂码图上可能耗时几十毫秒到上百毫秒直接堵住预览回调数据帧会堆叠画面卡顿甚至触发 ANR。正确做法是相机回调只负责投递解码放独立线程用一把锁保证同时只解一帧。public class QrDecoderThread { private final MultiFormatReader reader new MultiFormatReader(); private final AtomicBoolean busy new AtomicBoolean(false); private final ExecutorService executor Executors.newSingleThreadExecutor(); private volatile int previewWidth 640; private volatile int previewHeight 480; public QrDecoderThread() { MapDecodeHintType, Object hints new HashMap(); hints.put(DecodeHintType.POSSIBLE_FORMATS, Collections.singletonList(BarcodeFormat.QR_CODE)); // 实时场景不开 TRY_HARDER避免单帧耗时翻倍 hints.put(DecodeHintType.TRY_HARDER, Boolean.FALSE); hints.put(DecodeHintType.CHARACTER_SET, UTF-8); reader.setHints(hints); } public void submitFrame(byte[] data, int width, int height) { if (!busy.compareAndSet(false, true)) { return; // 上一帧还没解完直接丢弃当前帧 } previewWidth width; previewHeight height; executor.execute(() - { try { Result result decodeFrame(data, width, height); if (result ! null) { // 回调到 UI 线程实际项目里用 Handler 或 LiveData Log.d(QrDecoder, scanned: result.getText()); } } finally { busy.set(false); } }); } private Result decodeFrame(byte[] data, int width, int height) { PlanarYUVLuminanceSource source new PlanarYUVLuminanceSource( data, width, height, 0, 0, width, height, false); BinaryBitmap bitmap new BinaryBitmap(new HybridBinarizer(source)); try { return reader.decodeWithState(bitmap); } catch (NotFoundException e) { return null; // 这一帧没有码正常现象 } finally { reader.reset(); } } }代码逻辑说明busy 的 compareAndSet 是整条管线的闸门解不出来就丢帧避免解码线程积压导致相机缓冲区耗尽。singleThreadExecutor 保证解码严格串行decodeWithState 会复用 reader 内部状态比每次 buildHints 快但必须在 finally 里 reset()不然多帧之后状态残留会互相干扰。这段代码里几个关键选择都是有原因的POSSIBLE_FORMATS 只留 QR_CODE不给 DataMatrix因为每多一种格式 MultiFormatReader 就要多建一条尝试路径TRY_HARDER 关闭因为实时场景里码通常是完整可见的开它只增加耗时。如果你的业务要扫很小的码可以打开 TRY_HARDER同时把预览分辨率提到 1280×720换取更清晰的采样。相机侧配合 setPreviewCallbackWithBuffer 而不是 setPreviewCallback会稳定很多。前者要求你主动调用 addCallbackBuffer 归还数据GC 压力小、帧率稳。归还时一定复用同一个 byte[]每次 new 数组等于每帧都在申请内存。4.3 反色码与补光两个兜底分支现实的码不总是黑底白纹。部分设备屏显反色码、深色商品包装上印白码按正常码解会一直 NotFoundException。ZXing 提供 InvertedLuminanceSource把亮度取反后再走一遍二值化反色码立刻可解。LuminanceSource normal new PlanarYUVLuminanceSource( data, width, height, 0, 0, width, height, false); Result result tryDecode(normal); if (result null) { LuminanceSource inverted new InvertedLuminanceSource(normal); result tryDecode(inverted); }思路很简单先按正常码解失败再按反色码解。开销多一次二值化和一次 Reader 尝试实时场景完全可以接受。比在 UI 上放一个「反色模式」开关单帧切换更省心因为用户不知道手里的码是哪种自动兜底体验最好。补光的逻辑也一样暗光时预览帧平均亮度低于某个阈值就自动开手电比让用户手动找灯可靠。5. 避坑排查二维码扫不出的五种常见事故与调试顺序扫码率低的时候先别改代码按顺序核查四件事码本身是否规范、光照是否均匀、解码尺寸是否匹配、解码线程是否阻塞。绝大多数「时好时坏」都能落到这四类里。下面五条是从实际调试里捞出来的高频事故每条都按现象、原因、解决来写。5.1 暗光场景扫码率骤降白天却一切正常现象同一套代码白天亮堂的地方秒出傍晚或室内偏暗就反复失败偶尔成功一次要贴近屏幕。原因ZXing 二值化依赖于局部对比度环境亮度不足时码的黑色模块和背景的灰度差被压缩到阈值附近HybridBinarizer 切分出来的黑白点阵不稳定定位图形可能被断成两截。解决解码前评估帧平均亮度低于阈值时提高相机曝光补偿或自动打开闪光灯同时把解码区域往屏幕中心收窄排除四周暗角干扰。这里常见误区是反复调二值化阈值实际上 ZXing 的 HybridBinarizer 不接受外部阈值参数与其硬调不如先把环境光解决。真正需要动代码的是亮度判断和手电联动。中心裁剪这个做法注意别切掉码的定位边二维码四角至少留两个完整的定位图形在裁剪框内。5.2 深底浅纹的反色码怎么都扫不出现象手机屏幕显示深色背景白色二维码或者深色包装上印白码取景框里完全正常解码永远空结果。原因默认二值化把深色当成背景、浅色当模块反色码的明暗关系正好颠倒黑白位图整个反转Reader 找不到定位图形。解决按 4.3 的写法加一次 InvertedLuminanceSource 兜底正常解析失败后自动反转亮度再试一次。这个分支不要做成手动开关用户根本区分不了手里的码是不是反色。实测反面案例是有人为了「看起来高级」把反色分支放在了正常分支前面正常码反而被降权扫码优先走了反转流程速度明显变慢。正确的顺序永远是正常码优先反色只做异常兜底。5.3 预览画面清晰解码却一直超时现象预览流看起来锐利取景框里的码也很清楚但解码线程日志显示每帧要 80ms 以上帧率掉到每秒三帧以下。原因解码尺寸太大或者码在画面中占比太小。预览 1920×1080 全帧喂给 MultiFormatReader单个 QR 码只占画面 1/4 时Reader 要对整帧做多尺度滑窗耗时成倍增长。解决将解码区域按画面中心裁剪到 640×480 或 960×720码占比会明显放大或者把 YUV 数据降采样后再构造 LuminanceSource。用 setPreviewCallbackWithBuffer 减少 GC解码线程也能稳定跑更快。这条是我调扫码性能时最常用的一刀。中心裁剪不会影响扫码成功率因为用户本来就会把码放到取景框中间。代价是边缘的码扫不到所以裁剪比例要适可而止一般裁掉上下左右的 15%~25% 比较均衡。5.4 内容一长就生成失败或生成了扫不出现象短文本的二维码一切正常文案超过几百字后encode 直接抛异常或者生成成功但打印出来糊成一团。原因QR 码容量有硬上限字符多时字节模式会动态增加版本模块数size 固定 512 时模块密度剧增边缘间距急剧减小打印设备分辨率不够就把模块糊在一起。解决encode 前先估算内容长度纯数字、字母、汉字的上限不一样超过 300 字符的汉字内容要么升级到 1024 尺寸要么换 DataMatrix 码制后者在同等面积下能装更多数据。如果业务场景必须用 QR 码另一个做法是压缩内容——把长文本放服务端码里只放一个短 ID 或短链。绝大多数扫码场景最终读到的都是标识符把整篇文章塞进二维码属于性能浪费也会让扫描端的识别时间明显变长。5.5 中文内容生成正常扫出来却是乱码现象用 ZXing 生成的码自己解没问题换一个扫码 App 就乱码或者服务端批量生成的码别人手机扫出来是「锟斤拷」。原因生成时没有显式设置 EncodeHintType.CHARACTER_SET 为 UTF-8。QR 码字节模式默认字符集在 ZXing 里对中文支持不完整部分解码端会按 ISO-8859-1 去映射于是中文全部变成问号或乱码。解决生成端必须写死 hints.put(EncodeHintType.CHARACTER_SET, UTF-8)且放到 encode 的 hints 参数里解析端如果发现乱码优先排查生成端而不是解析端。排查乱码还有一个隐蔽点某些扫码 App 拿到 Result.getText() 后自己又做了一次编码转换把 UTF-8 字节当成 GBK 显示。这种情况在自研解码端不会出现在对接三方软件时要提前说好「字符集按 UTF-8 透传」不要二次转码。生产项目里我会在批量生成后随机抽样用不同扫码工具验证一遍才敢放量。6. 让扫码更抗造多格式识别、批量解析与解码节流多格式识别是最常见的进阶需求。ZXing 的 MultiFormatReader 支持 QR、DataMatrix、Aztec、Code128 等识别时 POSSIBLE_FORMATS 声明得越少越快。如果现场既有二维码又有 DataMatrix 货码可以这样配hints.put(DecodeHintType.POSSIBLE_FORMATS, Arrays.asList( BarcodeFormat.QR_CODE, BarcodeFormat.DATA_MATRIX, BarcodeFormat.AZTEC));注意 DataMatrix 和 QR 的定位图形差异很大Format 声明后 Reader 会自动切换策略。生产环境建议按业务白名单声明避免全格式开放带来的性能回退尤其是手持终端上跑全格式识别帧率会肉眼可见地下降。批量解析服务端图片时旋转问题比想象的频繁。手机相册导出的图经常带 EXIF 方向代码里只解一次容易漏。我一般会把原图按 0/90/180/270 各解一次for (int degrees : new int[]{0, 90, 180, 270}) { BufferedImage rotated rotate(image, degrees); try { return reader.decode(new BinaryBitmap(new HybridBinarizer( new RGBLuminanceSource(rotated)))).getText(); } catch (NotFoundException ignored) { } }四方向尝试只适合离线批处理实时扫码千万别这么干。实时场景里方向兜底应交给 TRY_HARDER 或 UI 引导省下每一毫秒都算赚到。解码节流是最后一道兜底。连续多帧没有码时不需要每帧都解常见做法是连续 10 帧失败后只在第 10 帧尝试解码中间 9 帧只做亮度统计。这样 CPU 占用可以再降一半。我现在的习惯是任何扫码需求都先问三件事——码的最小尺寸是多少、环境光最差能到什么程度、解码线程能不能保证单帧不阻塞。这三个答案一旦明确代码基本不会跑偏。踩了这么多次坑换来的这套顺序希望帮到你。本文还有配套的精品资源点击获取