如何用Java生成二维码

wen java案例 2026-08-10 4

如何用Java生成二维码：从入门到实战的完整指南（ZXing与QRGen详解）

📚 目录导读

二维码生成的核心原理与主流Java库对比
环境准备：Maven依赖与基础配置
实战案例一：使用ZXing库生成带Logo的彩色二维码
实战案例二：使用QRGen一行代码生成高清晰度二维码
高级技巧：动态数据、Base64转换与批量生成
常见问题解答（FAQ）与性能优化建议
如何选择适合你项目的方案

二维码生成的核心原理与主流Java库对比

二维码（QR Code）本质是将数据编码为黑白矩阵图案，通过纠错算法实现快速扫描，在Java生态中，最流行的两个库是谷歌的ZXing（Zebra Crossing）和开源社区活跃的QRGen。

如何用Java生成二维码

特性	ZXing	QRGen
核心优势	功能全面，支持条码+二维码	链式API极简，封装ZXing
依赖大小	约1.5MB	约800KB（含ZXing核心）
自定义能力	高（颜色、边距、缩放）	中（需传入MatrixToImageConfig）
学习曲线	稍陡	平缓（适合快速开发）

判断依据：若需解析、多格式支持，选ZXing；若只需快速生成,QRGen更高效。

环境准备：Maven依赖与基础配置

在pom.xml中添加以下依赖（以最新稳定版为例）：

<!-- ZXing核心与JavaSE扩展 -->
<dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>core</artifactId>
    <version>3.5.2</version>
</dependency>
<dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>javase</artifactId>
    <version>3.5.2</version>
</dependency>
<!-- QRGen（底层自动调用ZXing） -->
<dependency>
    <groupId>com.github.kenglxn.qrgen</groupId>
    <artifactId>javase</artifactId>
    <version>2.6.0</version>
</dependency>

基础配置提醒：

确保JDK版本≥8（建议11+，支持Optional类简化异常处理）。
生成路径需有写权限,若在Web容器中建议使用绝对路径。

实战案例一：使用ZXing生成带Logo的彩色二维码

核心代码讲解：

public static void generateWithLogo(String content, String logoPath, String outputPath) {
    try {
        int width = 300, height = 300;
        // 1. 指定编码格式与字符集
        Map<EncodeHintType, Object> hints = new HashMap<>();
        hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");
        hints.put(EncodeHintType.ERROR_CORRECTION, ErrorCorrectionLevel.H); // 高纠错以容纳Logo
        hints.put(EncodeHintType.MARGIN, 1); // 边距（单位：模块）
        // 2. 生成矩阵对象
        QRCodeWriter writer = new QRCodeWriter();
        BitMatrix matrix = writer.encode(content, BarcodeFormat.QR_CODE, width, height, hints);
        // 3. 自定义颜色（前景深蓝，背景浅灰）
        int foreground = 0xFF1E3A5F;
        int background = 0xFFE0E0E0;
        BufferedImage image = MatrixToImageWriter.toBufferedImage(matrix, 
                new MatrixToImageConfig(foreground, background));
        // 4. 叠加Logo（注意：Logo区域必须位于二维码中央，且尺寸不超过总面积的25%）
        if (logoPath != null) {
            BufferedImage logo = ImageIO.read(new File(logoPath));
            Graphics2D g = image.createGraphics();
            int x = (width - logo.getWidth()) / 2;
            int y = (height - logo.getHeight()) / 2;
            g.drawImage(logo, x, y, null);
            g.dispose();
        }
        ImageIO.write(image, "png", new File(outputPath));
    } catch (Exception e) {
        e.printStackTrace();
    }
}

关键点解析：

纠错级别H（30%容错）可保证Logo遮挡部分不影响扫描。
MatrixToImageConfig构造参数顺序：前景色（RGB）在左,背景色在右。

实战案例二：使用QRGen生成高清晰度二维码（含Base64输出）

QRGen封装了ZXing，提供流畅API，以下代码演示了直接输出Base64字符串,便于前后端分离场景使用：

import net.glxn.qrgen.javase.QRCode;
import net.glxn.qrgen.core.image.ImageType;
// 基础生成：PNG格式，500x500像素
File file = QRCode.from("https://example.com")
    .withSize(500, 500)
    .withColor(0xFF333333, 0xFFFFFFFF) // 前景色，背景色
    .withCharset("UTF-8")
    .file();
// 输出文件：new File("qrcode.png")
// 进阶：输出Base64字符串并持有多线程安全
ByteArrayOutputStream baos = QRCode.from("用户ID:12345")
    .withSize(800, 800)
    .withErrorCorrection(ErrorCorrectionLevel.H)
    .to(ImageType.PNG)
    .stream();
String base64 = Base64.getEncoder().encodeToString(baos.toByteArray());

注意：QRGen在2.x版本中withErrorCorrection接收的参数是net.glxn.qrgen.core.scheme.ErrorCorrectionLevel,需和ZXing的区分。

高级技巧：动态数据、批量生成与性能优化

1 动态数据（如URL带参数）

直接拼接字符串即可，但需注意UTF-8编码（中文场景必须指定字符集）。

2 批量生成（万级数据）

使用线程池并行生成，推荐核心线程数=CPU核心数。
选用PNG而非JPG（JPG有损压缩会破坏二维码识别率）。
缓存QRCodeWriter实例（非线程安全，但可在ThreadLocal中复用）。

3 内存优化

生成Base64字符串时，使用ByteArrayOutputStream避免频繁分配大数组，若图片过大，可考虑使用try-with-resources自动关闭流。

4 与Spring Boot集成

在Controller中返回ResponseEntity<byte[]>，设置Content-Type: image/png,可将二维码直接作为接口响应展示。

常见问题解答（FAQ）与性能优化建议

Q1：生成的二维码扫描不识别？

检查纠错级别是否太低（建议H），边距是否被截断（MARGIN设为1-2）。
贴到白底屏幕上测试,避免透明背景。

Q2：能否支持微信小程序码？

微信小程序码需调用微信官方接口，二维码规范不同（49位码）,纯Java方案不适用。

Q3：如何动态更换Logo并保持兼容？

固定Logo尺寸（建议80x80px），并确保用白色圆角边框包裹Logo区域,可提高识别率。

Q4：生成速度慢怎么办？

ZXing单次生成约10-30ms，主要耗时在IO写入，建议批量时重用BufferedImage,或先输出到内存流再批量落盘。

性能优化清单：

对于高频生成场景,预编译Hints映射表。
使用Graphics2D.setRenderingHint开启抗锯齿（仅对Logo绘制有效）。
在Linux无头环境下，设置java.awt.headless=true。

如何选择适合你项目的方案

项目类型	推荐方案	理由
企业级Web应用	ZXing + Spring Boot	可控性强，且便于后期扩展解析功能
轻量级工具/微服务	QRGen	减少样板代码，快速集成
需要Logo/样式定制	ZXing（自定义MatrixToImageConfig）	细节控制力更强
移动端后端	两者均可，建议QRGen+BASE64	减少图片文件管理成本

最后实践建议：无论选哪种，务必在生成前对内容做合法性校验（如长度限制、敏感词过滤），并对输出路径做安全防护，避免目录穿越，建议统一封装一个QrCodeService接口，内部可切换实现,未来升级无需改动业务代码。

附加SEO关键词：Java生成二维码教程、ZXing示例、QRGen依赖、带Logo二维码、二维码Base64转换、Spring Boot二维码接口。