Cypress在GitLab CI流水线执行失败问题咨询

看起来你遇到的核心问题是CI环境没有图形界面（GUI），但你的命令却在尝试启动Cypress的可视化界面，这在无头的CI环境里肯定会失败。下面一步步帮你排查和解决：

1. 检查你的npm脚本配置 #

首先，你提到本地执行npm run cypress run时会打开Cypress的GUI界面，这说明你的package.json里的scripts配置大概率有问题。比如如果你的脚本是这样的：

{
  "scripts": {
    "cypress": "cypress open"
  }
}

那npm run cypress run实际会被解析成cypress open run——也就是把"run"当成参数传给cypress open，这会让Cypress试图打开GUI界面，而CI环境没有显示设备，自然会启动失败。

正确的做法是把GUI打开和无头运行分成两个独立的脚本：

{
  "scripts": {
    "cypress:open": "cypress open", // 本地开发用这个打开GUI界面
    "cypress:run": "cypress run"    // CI流水线用这个无头运行测试
  }
}

本地开发时执行npm run cypress:open打开界面调试，CI里执行npm run cypress:run来自动运行测试。

2. 配置GitLab CI的运行环境 #

即使你用了cypress run，在GitLab CI的默认环境里可能还缺少Cypress运行需要的系统依赖（比如X11相关库，即使无头模式也需要这些基础库支持）。你可以通过两种方式解决：

方式一：手动安装系统依赖 #

在.gitlab-ci.yml的before_script里添加依赖安装步骤（适用于Ubuntu/Debian基础镜像）：

stages:
  - test

cypress-test:
  stage: test
  before_script:
    - npm install
    # 安装Cypress必需的系统依赖
    - apt-get update && apt-get install -y --no-install-recommends libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb
  script:
    - npm run cypress:run

方式二：使用Cypress官方Docker镜像 #

官方镜像已经预装了所有依赖，直接用它可以省去手动安装的麻烦，还能保证环境一致性：

stages:
  - test

cypress-test:
  stage: test
  image: cypress/base:18.17.0 # 选择和你项目匹配的Node版本镜像
  script:
    - npm install
    - npx cypress run --headless # --headless可省略，因为cypress run默认就是无头模式

3. 额外的优化建议 #

• 可以在CI里配置Cypress缓存，避免每次流水线都重新下载Cypress二进制文件，大幅加快运行速度：

cache:
  paths:
    - node_modules/
    - ~/.cache/Cypress/

• 如果你的测试需要访问外部服务，确保CI环境可以正常访问对应的地址，必要时配置网络代理或防火墙规则。

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