Java生成二维码：Zxing库使用教程

本文深入解析了Java中使用ZXing库生成高质量二维码的常见痛点与实战技巧，涵盖黑底白图的成因及正确配色方案、WriterException的精准排查方法、中文乱码的三大避坑要点、带Logo二维码模糊与识别率低的根本原因，以及容错等级在实际应用中的真实表现，帮助开发者避开默认配置陷阱、规避渲染兼容问题，并真正实现稳定、高扫率、专业级的二维码生成功能。

为什么 ZXing 生成的二维码图片是黑底白图，而不是白底黑图？

默认情况下，MatrixToImageConfig 的构造函数不传参时，会把黑色设为前景色（即二维码模块），白色为背景色——但 MatrixToImageWriter 实际写入图像时，**反过来了**：它把 0 当作白色、1 当作黑色，而 ZXing 内部用 0 表示空白区域、1 表示墨点。所以你看到的是“反相”结果。

• 正确做法是显式传入 new MatrixToImageConfig(Color.BLACK.getRGB(), Color.WHITE.getRGB())
• 别依赖默认值，ZXing 4.x 之后的默认配置在不同平台渲染可能不一致
• 如果用 BufferedImage.TYPE_INT_ARGB，记得提前清空背景为白色，否则透明底会导致扫码失败

MultiFormatWriter 报 WriterException 怎么快速定位？

这个异常基本都是输入不合法或参数越界导致的，不是运行时环境问题。重点看堆栈最内层的 cause：

• 出现 IllegalArgumentException: Data must be at least 1 character → 检查传入的 content 字符串是否为 null 或空格/空字符串
• 出现 WriterException: Can't encode message → 大概率是内容含不可编码字符（如某些 emoji、控制字符），改用 UTF-8 编码并设置 EncodeHintType.CHARACTER_SET
• 宽高设成 0 或负数也会触发，确保 width 和 height 都 > 0

中文内容生成失败或乱码的三个关键点

ZXing 默认不处理中文，必须手动指定字符集，否则会静默截断或抛异常。

• 一定要加 hint：hints.put(EncodeHintType.CHARACTER_SET, "UTF-8")
• 不要用 String.getBytes() 直接传字节数组给 encode()，MultiFormatWriter.encode() 接收的是原始字符串，编码由 hint 控制
• 如果内容含 URL，注意对特殊符号（如 &、=）做 URL 编码，否则扫码后跳转可能出错

生成带 Logo 的二维码，为什么中间图总糊或扫码率下降？

Logo 是后期叠加的，不是 ZXing 原生支持的功能。糊和识别率低，90% 是因为没控制好尺寸和透明度。

• Logo 宽高建议不超过二维码总宽的 20%，否则破坏定位图案（L 形角）
• 用 Graphics2D.drawImage() 绘制时，务必调用 setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR)
• 避免用 PNG 透明通道太深的 Logo 图，部分扫码器对 Alpha 混合兼容差；可先用 BufferedImage 转成纯 RGB 格式再贴

ZXing 对二维码容错能力有四个等级（L/M/Q/H），但很多人忽略：**加 Logo 后实际容错只剩一半左右**。哪怕选了 H 级，贴完图也容易扫不出来——这不是代码问题，是物理信息被覆盖了。

本篇关于《Java生成二维码：Zxing库使用教程》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！