无图形界面服务器Selenium报RenderCompositorSWGL帧缓冲错误

[GFX1-]: RenderCompositorSWGL failed mapping default framebuffer, no dt 属于无图形界面Linux环境下的浏览器渲染兼容错误，触发原因通常为三类：系统缺少浏览器软件渲染依赖的基础图形库、浏览器启动参数默认开启了不匹配无GUI环境的渲染特性、xvfb虚拟显示配置的色深/分辨率不符合帧缓冲映射要求，与Selenium脚本逻辑、URL传参错误无关联。

按顺序执行以下步骤，覆盖90%以上的同类型报错场景：

• 补全系统级图形渲染依赖
  先根据服务器的发行版安装对应依赖包，缺失基础渲染库是该报错的最高发诱因：
  • Debian/Ubuntu系执行命令：

    apt update && apt install -y libgl1-mesa-glx libgl1-mesa-dri libegl1-mesa libgbm1 libxcomposite1 libxdamage1 libxrandr2 libxtst6 libxss1 libasound2 libpangocairo-1.0-0 libatk-bridge2.0-0 libgtk-3-0 fonts-wqy-zenhei
    

  • RHEL/CentOS/AlmaLinux系执行命令：

    yum install -y mesa-libGL mesa-libEGL libgbm libXcomposite libXdamage libXrandr libXtst libXScrnSaver alsa-lib pango at-spi2-atk gtk3 wqy-zenhei-fonts
    

• 调整Selenium中浏览器的启动参数，强制禁用不兼容的渲染特性
  注意必须使用新版无头模式参数--headless=new，旧版--headless模式存在已知渲染兼容问题：
  • Firefox Selenium配置示例：

    FirefoxOptions options = new FirefoxOptions();
    options.addArguments("--headless=new");
    options.addArguments("--disable-gpu");
    options.addArguments("--disable-software-rasterizer");
    options.addArguments("--disable-dev-shm-usage");
    options.addPreference("gfx.webrender.all", false);
    options.addPreference("gfx.webrender.software", false);
    options.addPreference("layers.acceleration.disabled", true);
    // 后续绑定驱动、启动浏览器逻辑保持原有写法即可
    

  • Chromium/Chrome Selenium配置示例：

    ChromeOptions options = new ChromeOptions();
    options.addArguments("--headless=new");
    options.addArguments("--disable-gpu");
    options.addArguments("--disable-software-rasterizer");
    options.addArguments("--disable-dev-shm-usage");
    options.addArguments("--no-sandbox");
    options.addArguments("--disable-extensions");
    // 后续绑定驱动、启动浏览器逻辑保持原有写法即可
    

• 修正xvfb虚拟显示的运行配置
  默认xvfb-run命令分配的色深为8位，无法满足浏览器帧缓冲映射要求，不能直接包装程序运行：
  • 手动启动xvfb的正确命令：

    # 启动虚拟显示，指定24位色深、1080p分辨率
    Xvfb :99 -screen 0 1920x1080x24 &
    # 导出显示变量
    export DISPLAY=:99
    # 再执行Java Selenium程序
    java -jar your-selenium-program.jar
    

  • 直接用xvfb-run包装的正确参数：

    xvfb-run -s "-screen 0 1920x1080x24" java -jar your-selenium-program.jar
    

• 修复效果验证
  先不跑Selenium脚本，直接通过命令行调用浏览器验证环境是否正常，执行后无GFX报错、正常生成截图即为修复成功：

  # Firefox测试命令
  firefox --headless=new --disable-gpu --disable-software-rasterizer --screenshot https://example.com ff_test.png
  # Chromium测试命令
  chromium --headless=new --disable-gpu --disable-software-rasterizer --screenshot https://example.com cr_test.png
  

• 无需在URL传参格式问题上耗费排查时间，该问题与渲染报错无关联
• 无物理显卡的服务器环境不要开启WebRender、硬件加速类特性，此类配置必然触发渲染兼容错误
• 尽量使用稳定版（Stable Channel）的Firefox、Chromium二进制包，Beta/Nightly开发版本存在未修复的无头模式渲染bug

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