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

本文深入解析了使用ZXing库在Java中生成高质量二维码的常见痛点与实战技巧：从纠正默认黑底白图的底层逻辑（需显式配置MatrixToImageConfig以匹配0/1语义）、快速定位MultiFormatWriter异常根源（空内容、非法字符、尺寸越界），到确保中文正确编码的关键三步（强制UTF-8提示、避免手动字节转换、URL特殊符号转义），再到带Logo二维码的高可靠实现方案（严格控制Logo尺寸≤20%、启用双线性插值、预处理透明通道），并揭示加Logo后容错率骤降的本质原因——物理信息覆盖导致L/M/Q/H等级实际失效。每一步都直击开发者踩坑现场，提供可立即落地的精准解法。

为什么 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学习网公众号，带你了解更多关于的知识点！