简介：这是一份面向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，常见配置可以写成：

Map<DecodeHintType, 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 一个坐标，扫码界面全部自己写，这样才能控制预览、线程和权限。

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; Map<EncodeHintType, 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_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 直接吃 YUV

Android Camera 的 onPreviewFrame 回调给的是 YUV 格式的 byte[]，常见是 NV21。老式写法里有人先 YUV→Bitmap→RGBLuminanceSource，中间多两次全图转换，帧率直接掉一半。ZXing 专门为这种场景写了 PlanarYUVLuminanceSource，构造函数里指定数据、宽高和裁剪区域，它在内部直接从 Y 平面取亮度，不需要颜色转换。

这里有个容易错的地方：宽高必须传相机预览的实际尺寸，不是屏幕尺寸。预览 1920×1080，解码也按这个尺寸走；如果你嫌大，可以只传核心区域，比如中央 600×600 的矩形。拿屏幕尺寸去构造，亮度数组的偏移全错，结果是永远扫不出，且不报错，排查起来极像没有规律。

// data 来自 onPreviewFrame，width/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() { Map<DecodeHintType, 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 占用可以再降一半。我现在的习惯是：任何扫码需求都先问三件事——码的最小尺寸是多少、环境光最差能到什么程度、解码线程能不能保证单帧不阻塞。这三个答案一旦明确，代码基本不会跑偏。踩了这么多次坑换来的这套顺序，希望帮到你。

本文还有配套的精品资源，点击获取