在Jenkins运行Maven项目遇WindowServer连接失败问题求助

我之前在Mac上部署全局Jenkins时碰到过一模一样的报错，折腾了好一阵才找到可行的解决方向，给你几个亲测有效的方案：

1. 确保Jenkins以当前登录用户身份运行 #

就算迁移到LaunchAgents，如果plist配置里的运行用户不是当前登录用户，依然拿不到GUI会话权限：

• 打开Jenkins的plist文件（路径一般是~/Library/LaunchAgents/org.jenkins-ci.plist）
• 检查并修改<key>UserName</key>对应的内容为你的当前用户名，比如：

  <key>UserName</key>
  <string>your-mac-username</string>
  

• 重启Jenkins服务：

  launchctl unload ~/Library/LaunchAgents/org.jenkins-ci.plist
  launchctl load ~/Library/LaunchAgents/org.jenkins-ci.plist
  

2. 给Jenkins赋予系统隐私权限 #

Mac的隐私安全机制会阻止后台进程访问WindowServer，需要手动添加权限：

• 打开「系统设置」->「隐私与安全性」
• 找到「屏幕录制」，点击加号，添加Jenkins进程（或者找到Java进程，因为Jenkins基于Java运行）
• 同样在「辅助功能」列表里也添加该进程
• 完成后重启Jenkins

3. 手动指定DISPLAY环境变量 #

Mac的GUI会话依赖DISPLAY变量，后台启动的Jenkins可能没有自动获取到：

• 编辑LaunchAgents里的plist文件，添加环境变量配置：

  <key>EnvironmentVariables</key>
  <dict>
      <key>DISPLAY</key>
      <string>:0</string>
  </dict>
  

• 保存后重新加载Jenkins服务

4. 用虚拟显示器规避真实GUI依赖 #

如果你的Maven项目里有插件需要GUI交互（比如某些打包、测试插件），可以用Xvfb模拟虚拟显示器：

• 先通过Homebrew安装Xvfb：brew install Xvfb
• 在Jenkins的Maven构建步骤里，把命令改成：

  xvfb-run mvn clean install
  

这样Jenkins会在虚拟显示器环境下执行Maven命令，不需要连接真实的WindowServer

5. 检查Jenkins的JAVA_OPTS配置 #

如果Jenkins启动时加了-Djava.awt.headless=true参数，会强制进入无头模式，直接导致无法连接WindowServer：

• 打开Jenkins的配置文件（比如/Users/Shared/Jenkins/Home/config.xml）
• 查找JAVA_OPTS相关配置，去掉-Djava.awt.headless=true参数
• 重启Jenkins服务

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