使用自托管容器Runner执行cypress run时遇exit code 255错误求助

以下是针对自托管GitHub Actions容器环境中Cypress运行返回exit code 255的常见排查和解决方法：

1. 补全容器系统依赖 #

Cypress运行需要特定系统库支持，自托管容器镜像往往默认缺失这些依赖。如果是Debian/Ubuntu系镜像，在工作流或Dockerfile中添加以下安装步骤：

apt-get update && apt-get install -y \
  libgtk2.0-0 libgtk-3-0 libgbm-dev \
  libnotify-dev libgconf-2-4 libnss3 \
  libxss1 libasound2 libxtst6 xauth xvfb

2. 修复权限与缓存问题 #

自托管容器的权限配置可能导致Cypress无法读写缓存目录：

• 手动指定缓存目录并赋予权限：

  mkdir -p /tmp/cypress-cache
  chmod -R 777 /tmp/cypress-cache
  export CYPRESS_CACHE_FOLDER=/tmp/cypress-cache
  

• 强制重新安装Cypress，避免缓存损坏：

  npx cypress install --force
  

3. 调整GitHub Actions工作流配置 #

• 配置虚拟显示器：Cypress需要图形环境支持，在运行cypress run前启动Xvfb：

  Xvfb :99 -screen 0 1024x768x24 &
  export DISPLAY=:99
  

• 固定Node.js版本：确保工作流使用的Node.js版本与本地开发环境一致，避免版本兼容问题：

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '18' # 替换为你的项目Node版本
  

4. 排查测试代码与运行日志 #

• 启用verbose日志定位错误：

  cypress run --verbose
  

  日志中会显示进程崩溃的具体原因，比如未捕获的异常、依赖服务无法访问等。
• 检查测试用例中的异步操作是否正确处理，避免未捕获的Promise rejection导致进程异常退出。

5. 调整容器资源配额 #

自托管容器的内存、CPU不足可能导致Cypress进程崩溃：

• 检查容器的资源限制，适当增加内存分配（比如从512MB调整到2GB）。
• 减少Cypress并行测试的数量，避免资源耗尽：

  cypress run --parallel --ci-build-id $GITHUB_RUN_ID --num-workers 2 # 根据资源调整worker数量
  

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