如何在Jenkins Pipeline（无头模式）中运行PyAutoGUI？

pyautogui依赖真实的X11显示环境才能模拟键鼠操作，而Jenkins无头模式默认没有这个环境，这就是你遇到问题的核心原因。以下是几个可行的解决思路：

方案一：在Python容器中配置Xvfb虚拟显示 #

针对你当前使用的Python容器，只需在测试前安装并启动Xvfb（虚拟X11服务器），让pyautogui有可用的显示环境。修改你的Pipeline脚本如下：

stages {
    stage('Test') {
        steps {
            container(name:'python'){
                sh """
                echo '********* Build Stage Started **********'
                # 安装Xvfb及依赖工具
                apt-get update && apt-get install -y xvfb x11-utils
                # 安装依赖包
                pip install --upgrade pip
                pip install selenium-wire pyautogui behave
                # 启动虚拟显示，分辨率设为1920x1080，24位色深
                Xvfb :1 -screen 0 1920x1080x24 &
                # 让后续命令使用这个虚拟显示
                export DISPLAY=:1
                # 可选：验证显示环境是否正常
                xdpyinfo
                # 运行测试用例
                behave -D browser=remote features/Aggregation/avg.feature --tags=@createTransformation
                """
            }
        }
    }
}

说明 #

Xvfb会创建一个不依赖物理屏幕的虚拟X11显示，pyautogui通过DISPLAY环境变量识别并使用这个显示，从而绕过无头模式的限制。

方案二：更换为带桌面环境的Docker镜像 #

如果你的Python容器基于轻量级镜像（如alpine、slim），可以直接换成预装X11桌面环境的镜像（比如python:3.10-bullseye），这类镜像无需额外安装Xvfb，只需在脚本中设置DISPLAY=:0即可使用默认显示环境。不过这种镜像体积更大，适合对镜像体积不敏感的场景。

方案三：用Selenium原生API替代pyautogui（推荐） #

如果你的操作场景允许，优先用Selenium的ActionChains或原生交互API替代pyautogui，这类API完全基于Selenium会话，不需要依赖本地显示环境，更适配Jenkins的无头CI/CD场景。示例代码：

from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.keys import Keys

# 模拟点击元素+回车
action = ActionChains(driver)
action.click(target_element).send_keys(Keys.ENTER).perform()

# 模拟鼠标移动
action.move_to_element(target_element).perform()

说明 #

这种方式不需要额外配置显示环境，所有操作都在Selenium控制的浏览器会话中执行，稳定性和兼容性更好。

内容的提问来源于stack exchange，提问作者Mohamed Amine Nouir