Java初学者项目实战：开发一个简易的二维码生成器

Java生成二维码需引入zxing的javase模块（3.5.3版），显式设置UTF-8编码和H级容错，用BufferedImage+白底渲染避免模糊或黑块，路径含中文时确保环境UTF-8编码。

Java 生成二维码本身不难，但初学者常卡在依赖引入失败、中文乱码、输出图片模糊或路径写错这几个地方。用 zxing 是最稳妥的选择，别碰那些包装过头的“一键生成”工具类。

用 Maven 引入 zxing 的正确坐标

别用旧版 core 单独依赖——它只负责编码逻辑，不带图像输出能力；必须同时加 javase 模块，否则调 MatrixToImageWriter.writeToPath() 会报 NoClassDefFoundError。

  com.google.zxing
  javase
  3.5.3

• 版本选 3.5.3（最新稳定版），3.6.0 开始要求 Java 11+，初学者用 JDK 8/11 都兼容的 3.5.3 更省心
• 如果用 Gradle，写成 implementation 'com.google.zxing:javase:3.5.3'，别漏掉 :javase
• 手动下载 jar 包的同学：必须同时放 core-3.5.3.jar 和 javase-3.5.3.jar 进 classpath

生成含中文的二维码不乱码的关键设置

默认编码是 ISO-8859-1，一写中文就变方块或抛 WriterException。必须显式指定字符集为 UTF-8，且要传进 EncodeHintType.CHARACTER_SET 这个 hint。

Map hints = new HashMap<>();
hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");
hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.H); // 推荐 H 级容错
BitMatrix bitMatrix = new MultiFormatWriter().encode(content, BarcodeFormat.QR_CODE, width, height, hints);

• content 字符串本身用 UTF-8 编码保存源文件即可，不用额外 new String(content.getBytes("GBK"), "UTF-8") 转来转去
• 容错等级选 H（30% 损毁可恢复），比默认的 L（7%）更实用，尤其扫码环境光线差时
• 如果提示 “Content too long”，不是代码错，是内容超出了当前尺寸能容纳的码字上限——要么压缩文本，要么调大 width/height

保存为 PNG 时图片模糊或空白的常见原因

直接用 MatrixToImageWriter.writeToPath() 写出的图有时边缘发虚、有灰边，甚至全黑——根本原因是默认渲染质量低，且没处理透明背景。

堆友

Alibaba Design打造的设计师全成长周期服务平台，旨在成为设计师的好朋友

下载

立即学习“Java免费学习笔记（深入）”；

BufferedImage image = MatrixToImageWriter.toBufferedImage(bitMatrix);
// 关键：开启抗锯齿 + 设置背景为白色
image = toWhiteBackground(image);
ImageIO.write(image, "PNG", new File(outputPath));

其中 toWhiteBackground() 可简单实现：

private static BufferedImage toWhiteBackground(BufferedImage src) {
    BufferedImage dest = new BufferedImage(src.getWidth(), src.getHeight(), BufferedImage.TYPE_INT_ARGB);
    Graphics2D g2d = dest.createGraphics();
    g2d.setColor(Color.WHITE);
    g2d.fillRect(0, 0, dest.getWidth(), dest.getHeight());
    g2d.drawImage(src, 0, 0, null);
    g2d.dispose();
    return dest;
}

• 别用 TYPE_INT_RGB，它不支持 alpha 通道，遇到 zxing 默认生成的半透明像素会出黑块
• 如果输出路径含中文（如 "D:\\我的二维码\\code.png"），File 构造没问题，但确保运行环境终端/IDE 的默认编码是 UTF-8，否则可能抛 FileNotFoundException
• 宽高建议设为 300×300 或 400×400，太小（如 100×100）会导致手机扫码困难

真正麻烦的不是生成逻辑，而是把 BitMatrix 转成清晰、兼容性好、带白底的 PNG 这一步——初学者容易以为“能出图就行”，结果扫不出来才回头折腾。留心 BufferedImage 类型和背景填充，比反复调参数有用得多。