Debian Java 图形界面显示异常排查与修复
一 快速判断与对应处理
出现错误提示：Can’t connect to X11 window server
说明没有可用的 X11 显示环境。若在服务器/无界面环境，启用无头模式：在启动参数中加入 -Djava.awt.headless=true；若本机有桌面并需要弹出窗口，正确设置 DISPLAY（如：export DISPLAY=:0 或 127.0.0.1:0.0），并确保 Xorg 已运行且当前用户有权限访问（如加入 xhost +local: 仅本机测试用）。在 Tomcat 中可在 bin/catalina.sh 的 JAVA_OPTS/CATALINA_OPTS 添加该参数并重启。
服务器/容器环境仅做渲染（报表、图片、流程图）不需要可见窗口
直接使用无头模式：添加 -Djava.awt.headless=true，可避免依赖 X11，稳定完成图形渲染任务。
桌面环境 Java 程序窗口空白、组件错位或不显示
优先检查代码：确保组件已加入父容器、调用 setVisible(true)、布局管理器使用正确；必要时在入口处显式设置可见性，避免空窗口。
二 中文显示为方块或乱码
安装中文字体并刷新缓存
在 Debian 安装常用中文字体（如 fonts-wqy-zenhei），然后执行 fc-cache -f -v 刷新字体缓存：
sudo apt-get install fonts-wqy-zenhei
fc-cache -f -v
让 JRE 能找到中文字体
方式一：在 $JAVA_HOME/jre/lib/fonts 下创建 fallback 目录，拷贝/软链中文字体（如 wqy-zenhei.ttf 或 Windows 的 simsun.ttc），执行 mkfontdir/mkfontscale 后重启应用。
方式二：确认系统字体路径已存在并可用，执行 fc-list :lang=zh 查看可用中文字体。
统一字符编码为 UTF-8
启动参数加入 -Dfile.encoding=UTF-8，并确保系统与应用层均使用 UTF-8，可减少中文处理不一致导致的乱码。
三 运行环境与版本冲突排查
多版本 Java 并存导致行为不一致
使用 update-alternatives 管理并切换默认版本：
sudo update-alternatives –config java
必要时在用户环境或 /etc/environment 中校正 JAVA_HOME/PATH，避免调用到错误版本。
依赖库缺失导致图形组件异常
安装常见 X11 依赖（示例）：
sudo apt-get install libxrender1 libxtst6
然后重启应用或会话。
四 Tomcat 与服务的落地配置示例
无头渲染场景（推荐在 catalina.sh 的 JAVA_OPTS/CATALINA_OPTS 中设置）
JAVA_OPTS=“$JAVA_OPTS -Djava.awt.headless=true”
或
CATALINA_OPTS=“$CATALINA_OPTS -Djava.awt.headless=true”
修改后重启 Tomcat，观察 catalina.out 日志。
需要显示 GUI 的桌面环境
确保 DISPLAY 正确（如 :0），X11 服务运行，用户具备访问权限；若在 systemd 服务中运行，需配置合适的 User/Group 与 XDG_RUNTIME_DIR，避免权限或会话隔离导致无法连接 X Server。
五 最小自检清单