GitLab CI中Cypress测试偶发启动失败问题求助

问题背景 #

基于Next.js、MUI和TypeScript的项目，使用Cypress开展组件测试，本地执行npm run test完全正常，但GitLab CI中测试偶发启动失败，报错「Missing X server or $DISPLAY」。无修改连续重跑4次，前3次失败、第4次成功；失败时会清理core.70这类core dump文件，成功时清理的是.next/、next-env.d.ts等项目文件。已尝试更换镜像、设置export DISPLAY、调整--headless参数等操作，均未解决问题。

问题分析 #

从日志对比可发现：

• 失败与成功的任务运行在不同runner节点（Builder 2 vs Builder 1），节点环境存在差异或残留资源干扰
• 失败时出现core dump文件，说明之前的运行可能崩溃留下残留，导致Chrome初始化环境异常
• 尽管使用--headless参数，部分Chrome版本在headless模式下仍可能残留X11相关初始化逻辑，偶发触发依赖缺失报错

解决方案 #

1. 强制Chrome使用无X依赖的Headless Ozone平台 #

修改package.json中的测试脚本，添加Chrome启动参数，彻底跳过X环境检测：

"scripts": {
    ...
    "test": "cypress run --component --browser chrome --headless -- --no-sandbox --disable-gpu --ozone-platform=headless"
}

--ozone-platform=headless会让Chrome完全不依赖X11环境，从根源避免相关报错。

2. 提前清理所有残留文件 #

在CI脚本中添加前置清理步骤，确保每次运行环境完全干净：

# Test Stage
test:
    image: cypress/browsers:node18.12.0-chrome107
    script:
        - rm -rf core.* .next/ next-env.d.ts node_modules/
        - npm ci
        - npm run test

3. 在Cypress配置中全局指定Chrome启动参数 #

修改cypress.config.ts，配置Chrome默认启动参数，解决Docker环境下的常见问题：

import { defineConfig } from 'cypress';

export default defineConfig({
    e2e: {
        setupNodeEvents(on, config) {},
        excludeSpecPattern: ['**/examples/**/*'],
        baseUrl: 'http://localhost:3000',
        video: false,
    },

    component: {
        devServer: {
            framework: 'next',
            bundler: 'webpack',
        },
        video: false,
        browserLaunchOptions: {
            chrome: {
                args: [
                    '--no-sandbox',
                    '--disable-gpu',
                    '--ozone-platform=headless',
                    '--disable-dev-shm-usage' // 解决Docker共享内存不足问题
                ]
            }
        }
    },
});

4. 切换到预配置镜像或使用Xvfb模拟环境 #

如果上述方法无效，可尝试使用Cypress官方预配置的cypress/included镜像：

test:
    image: cypress/included:12.12.0
    script:
        - npm ci
        - npm run test

或者在现有镜像中安装Xvfb模拟X环境：

test:
    image: cypress/browsers:node18.12.0-chrome107
    script:
        - apt-get update && apt-get install -y xvfb
        - xvfb-run --auto-servernum npm run test

验证 #

执行上述修改后，重新运行GitLab CI流水线，可解决偶发的X server依赖报错，确保测试稳定运行。

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