Desktop.getDesktop().browse() 报 java.awt.HeadlessException 是因在无图形界面环境（如 Linux 无 X11、Docker 默认）下运行，需先调用 isDesktopSupported() 判断支持性，再检查 isSupported(Desktop.Action.BROWSE)，否则必然失败。
Desktop.getDesktop().browse() 报错 java.awt.HeadlessException
这是最常见问题：程序在无图形界面的服务器环境（比如 Linux 无 X11、Docker 容器默认配置）下运行时，Desktop 根本不可用。它依赖本地桌面环境支持，不是纯 Java 实现。
- 先用
Desktop.isDesktopSupported()判断——不检查就调用getDesktop()必然崩 - 再用
Desktop.getDesktop().isSupported(Desktop.Action.BROWSE)确认 browse 功能可用，有些系统（如某些 macOS 终端会话）可能禁用该行为 - Docker 中想让它工作？得加
--env="DISPLAY=:1" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw"并运行 X server，但通常不现实——这时应改用 fallback 方案（比如生成 URL 文本提示用户手动打开）
open mailto: 链接时中文参数乱码或被截断
mailto: 是 URI，必须严格编码。Java 的 URLEncoder.encode() 默认按 application/x-www-form-urlencoded 编码，但邮件客户端只认 RFC 2368 要求的 %xx 编码，且仅对非 ASCII 字符和保留字符（如空格、@、?）做处理，不能全量编码。
- 别用
URLEncoder.encode("张三", "UTF-8")直接拼进mailto:——它会把@变成%40，导致邮箱地址解析失败 - 正确做法：只对 subject/body 中的中文和特殊符号用
java.net.URLEncoder.encode(str, "UTF-8").replace("+", "%20")，然后手动拼接，例如："mailto:test@example.com?subject=" + encodedSubject + "&body=" + encodedBody - 注意 body 换行要用
%0D%0A（CRLF），不能用\n或\r\n字符本身
Linux 下 Desktop.browse() 打不开浏览器，但命令行里 xdg-open 正常
这是因为 Desktop 在 Linux 上底层调用的就是 xdg-open，但它依赖环境变量和 JVM 启动上下文。常见失效场景是：JVM 由 systemd 服务、cron 或后台脚本启动，没继承用户的 DISPLAY / DBUS_SESSION_BUS_ADDRESS。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 检查当前进程能否执行
xdg-open https://example.com——如果命令行也失败，说明不是 Java 问题，而是环境缺失 - 确保
DISPLAY和DBUS_SESSION_BUS_ADDRESS已导出，后者尤其关键（DBus 用于跨进程唤醒浏览器） - 避免在 root 用户或独立 session 下运行；若必须后台触发，考虑用
su -l $USER -c 'xdg-open ...'代理执行，而不是依赖Desktop
macOS 上打开链接跳转到 Safari 而非用户设置的默认浏览器
macOS 的 Desktop.browse() 实际调用的是 NSWorkspace.sharedWorkspace().openURL()，理论上走系统默认，但部分 Java 版本（尤其是旧版 JRE 或非 Oracle JDK）存在桥接 bug，会绕过用户偏好，直奔 Safari。
立即学习“Java免费学习笔记（深入）”；
- 升级到 JDK 17+（特别是 Temurin/Azul 构建版本），这个问题在多数新版本中已修复
- 验证系统默认是否真生效：终端执行
defaults read NSGlobalDomain NSDefaultWebBrowser，看返回值是否为你期望的浏览器 Bundle ID - 如果仍异常，可临时 fallback 到
Runtime.getRuntime().exec(new String[]{"open", "-a", "Google Chrome", url})，但需硬编码浏览器名，兼容性差
Desktop 类看着简单，但它的行为高度依赖操作系统状态、用户 session、JVM 启动方式和 JDK 实现细节。写之前先查 isSupported()，出错后优先怀疑环境而非代码——这点比怎么写更重要。
