Spring Boot中从应用入口组件创建Swing窗口为何触发HeadlessException？

阿华AIGC实验室

2026-5-21

解决Spring Boot中创建Swing/AWT窗口时的HeadlessException问题

这个异常的核心原因很明确：Spring Boot默认会以headless（无头）模式启动，这种模式是为了适配无图形界面的服务器环境，JVM在该模式下会禁用所有与AWT/Swing相关的图形支持，所以当你尝试创建Swing窗口时就会抛出HeadlessException。

下面是几种可行的解决方案，按优先级推荐：

1. 禁用Spring Boot的headless模式

有三种便捷方式可以实现：

方式一：在main方法中提前设置系统属性

在启动Spring Boot应用之前，先手动设置java.awt.headless为false，确保JVM启用图形支持：

@SpringBootApplication
public class SwingBootDemo {
    public static void main(String[] args) {
        // 关键：禁用headless模式
        System.setProperty("java.awt.headless", "false");
        
        // 启动Spring Boot上下文
        ConfigurableApplicationContext context = SpringApplication.run(SwingBootDemo.class, args);
        
        // 后续创建Swing窗口的逻辑...
    }
}

方式二：通过application.properties配置

在项目的src/main/resources/application.properties中添加一行配置，让Spring Boot自动禁用headless模式：

spring.main.headless=false

方式三：通过启动参数传递

如果是打包成jar后运行，可以在启动命令中添加JVM参数：

java -Djava.awt.headless=false -jar your-spring-boot-app.jar

2. 确保Swing组件在EDT线程中初始化

即使禁用了headless模式，直接在main线程创建Swing组件也可能引发线程安全问题（Swing是单线程模型）。正确的做法是把窗口创建逻辑放在**事件调度线程（EDT）**中执行，用SwingUtilities.invokeLater()包裹：

// 接上面的main方法
SwingUtilities.invokeLater(() -> {
    JFrame mainFrame = new JFrame("Spring Boot + Swing App");
    mainFrame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    mainFrame.setSize(400, 300);
    mainFrame.add(new JLabel("Hello from Spring Boot!", SwingConstants.CENTER));
    mainFrame.setLocationRelativeTo(null); // 居中显示
    mainFrame.setVisible(true);
});