SSH启动Java程序报HeadlessException：未设置X11 DISPLAY变量

错误原因 #

这个报错和Java无头版本无关，核心问题是SSH默认连接时未启用X11转发，导致程序运行时无法找到X11显示环境（DISPLAY变量未设置），而java.awt.Desktop类必须依赖图形界面环境才能完成调用浏览器的操作。

解决方法 #

1. 启用SSH X11转发（需本地有X服务器支持）

如果需要在本地机器显示服务器端打开的浏览器窗口：

• Linux/macOS终端连接服务器时，添加-X参数开启X11转发：

  ssh -X username@your-server-ip
  

• Windows用户使用PuTTY等工具时，需在软件设置中开启X11转发选项，同时本地要运行X服务器（如Xming、VcXsrv）
• 连接成功后，先执行echo $DISPLAY确认变量已正常设置，再启动Java程序

2. 修改Java代码，绕过图形环境依赖

如果不需要在服务器端显示浏览器，可替换Desktop.getDesktop().browse()的逻辑，直接调用系统命令打开链接：

import java.io.IOException;

public class Server {
    public static void openURL(String url) throws IOException {
        String os = System.getProperty("os.name").toLowerCase();
        Runtime runtime = Runtime.getRuntime();
        
        if (os.contains("win")) {
            runtime.exec("rundll32 url.dll,FileProtocolHandler " + url);
        } else if (os.contains("mac")) {
            runtime.exec("open " + url);
        } else if (os.contains("nix") || os.contains("nux")) {
            runtime.exec(new String[]{"xdg-open", url});
        }
    }
}

注：这种方式在无图形环境的服务器上可能无效，需服务器本身配置了可无界面调用的浏览器工具

3. 强制Java关闭无头模式（不推荐）

启动Java程序时添加参数强制禁用无头模式，但前提是已配置好X11转发和DISPLAY变量：

java -Djava.awt.headless=false Server

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