如何解决Spring Boot中图片弹窗GUI引发的Headless Exception？

问题原因 #

Spring Boot默认以headless模式启动（适配无图形界面的服务器环境），在该模式下Java不允许创建AWT/Swing等GUI组件，因此调用display方法弹出图片时会触发Headless Exception。另外如果GUI代码没有在事件调度线程（EDT）中执行，也可能加剧这类问题，但核心原因还是headless模式的限制。

解决方案 #

1. 关闭Spring Boot的Headless模式 #

有三种方式可以关闭该模式：

• JVM参数方式：启动程序时添加参数

  -Djava.awt.headless=false
  

• 启动类代码设置：在Spring Boot启动类中修改配置

  public static void main(String[] args) {
      SpringApplication app = new SpringApplication(YourApplicationClass.class);
      app.setHeadless(false);
      app.run(args);
  }
  

• 配置文件方式：在application.properties中添加

  spring.main.headless=false
  

  或在application.yml中配置：

  spring:
    main:
      headless: false
  

2. 确保GUI代码在事件调度线程（EDT）中执行 #

AWT/Swing组件的创建和更新必须在EDT中进行，否则可能引发线程安全问题或异常，修改display方法：

import javax.swing.SwingUtilities;

public void display() {
    SwingUtilities.invokeLater(() -> {
        // 这里编写你的图片显示逻辑，比如创建JFrame、加载并显示图片等
        JFrame frame = new JFrame("图片预览");
        // ... 其他GUI操作
        frame.setVisible(true);
    });
}

3. 适配无图形界面的运行环境 #

如果程序需要在服务器等无图形界面的环境运行，上述方法无法解决问题，可选择：

• 使用虚拟显示工具（如Xvfb）模拟图形环境
• 调整程序逻辑，避免在服务器环境触发GUI弹出操作，改为生成图片文件提供下载等替代方案

内容的提问来源于stack exchange，提问作者Eric Liu