You need to enable JavaScript to run this app. Spring Boot启动上下文后Barbecue生成的条码未显示文本问题
优惠活动
大模型
产品
解决方案
定价
更多

Spring Boot启动上下文后Barbecue生成的条码未显示文本问题

问题核心根因

这个反常现象的本质是Spring Boot的默认启动流程会强制将JVM的java.awt.headless属性设置为true,和你引入的老旧barbecue 1.5-beta1库的AWT实现存在兼容性冲突:

  • 不初始化Spring Boot上下文时,JVM默认处于headless=false状态,AWT可以正常加载屏幕相关的字体渲染配置,条码下方的文本可以正常绘制
  • 一旦执行SpringApplication.run(),Spring Boot为了避免无图形界面的服务器环境下启动卡滞,会默认打开headless模式。而1.5-beta1版本的Barbecue在headless环境下的文本绘制逻辑没有做兼容处理:代码会尝试查询本地屏幕环境的字体配置,headless模式下拿不到对应配置时不会抛出异常,直接跳过文本绘制步骤。好在竖条部分是基于内存BufferedImage绘制的,完全不依赖屏幕环境,所以不会出现条码本身画不出来的问题,只有下方的文本会消失。

快速验证方法

你可以不修改业务逻辑,仅通过调整系统属性复现/消除这个问题,确认根因:

  • 在main方法最开头手动设置System.setProperty("java.awt.headless", "false");,再启动Spring Boot,会发现条码文本可以正常显示
  • 不启动Spring Boot,仅手动设置System.setProperty("java.awt.headless", "true");,会复现“条码无文本”的问题

适配生产环境的解决方案

不要为了这个问题把headless模式关掉——毕竟生产服务器本身没有图形界面,关闭headless反而会引发其他AWT初始化的问题,推荐采用这些可落地的方案:

  • 最稳妥的方案:不要依赖Barbecue内部的文本绘制能力,在拿到Barbecue生成的纯条码BufferedImage之后,自己基于标准Graphics2D在图片下方叠加绘制文本。这个方案完全不受headless模式影响,还能自由调整文本位置、字体、大小
    参考实现片段:
    public static BufferedImage wrapBarcodeWithText(BufferedImage pureBarcode, String barcodeText) {
        // 预留25px高度用于放置文本
        int finalImgHeight = pureBarcode.getHeight() + 25;
        BufferedImage finalImage = new BufferedImage(
                pureBarcode.getWidth(), finalImgHeight, BufferedImage.TYPE_INT_ARGB
        );
        Graphics2D g = finalImage.createGraphics();
        // 先绘制条码主体
        g.drawImage(pureBarcode, 0, 0, null);
        // 设置字体
        Font customFont = new Font("Monospaced", Font.PLAIN, 20);
        g.setFont(customFont);
        // 计算文本居中位置
        FontMetrics fm = g.getFontMetrics(customFont);
        int textStartX = (finalImage.getWidth() - fm.stringWidth(barcodeText)) / 2;
        int textStartY = pureBarcode.getHeight() + fm.getAscent();
        // 绘制黑色文本
        g.setColor(Color.BLACK);
        g.drawString(barcodeText, textStartX, textStartY);
        g.dispose();
        return finalImage;
    }
    
  • 备选方案:如果要沿用Barbecue原生的文本绘制逻辑,可以在初始化SpringApplication时手动关闭默认的headless设置,代码为new SpringApplicationBuilder(App.class).headless(false).run(args),但这个方案不推荐在无桌面的服务器环境下长期使用
  • 备选方案:替换为后续修复了headless兼容问题的Barbecue正式版本,注意做好平滑迁移

内容的提问来源于stack exchange,提问作者Kihats

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.12 05:36:05