WSL2环境下Java使用Robot类报headless/X11连接错误如何解决

算力阿峰

2026-9-27

问题根因

Java AWT包下的Robot类需要依托图形窗口环境实现键鼠模拟、屏幕截图等功能，WSL2默认启用无头模式（headless）且未内置X11窗口服务，因此会触发两类报错。

解决方案

按照以下步骤配置即可解决：

第一步：配置X11窗口服务
可选两种方案：
1. 启用微软官方WSLg组件：WSL2 0.51.3及以上版本支持内置WSLg图形支持，执行wsl --update升级到最新版WSL后，在WSL配置中开启图形支持即可，无需额外安装第三方软件
2. 安装第三方X服务：Windows侧安装VcXsrv类X11服务软件，启动时勾选「Disable access control」、「Native opengl」选项，同时允许该软件通过Windows防火墙的入站请求
第二步：配置WSL2侧DISPLAY环境变量
编辑当前shell的配置文件（~/.bashrc对应Bash、~/.zshrc对应Zsh），在末尾添加对应配置：
- 用WSLg的场景：
```
export DISPLAY=:0
```
- 用第三方X服务的场景：
```
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0.0
```
配置完成后执行source ~/.bashrc（对应替换为你的配置文件路径）让配置生效。

第三步：调整Java代码配置
必须在所有AWT类加载之前设置headless属性，修改后代码如下：

import java.awt.AWTException;
import java.awt.Robot;


public class AutoSell {
  
    public static void main(String[] args) throws AWTException  {
        // 必须放在最开头，优先于所有AWT类加载
        System.setProperty("java.awt.headless", "false");
        Robot robot = new Robot();
        robot.delay(1000);
        System.out.println("test");
      
        }
    }