Vue/NuxtJS项目Cypress代码覆盖率报告生成失败及配置报错求助

大部分人配置失败的核心原因是：将babel-plugin-istanbul全局注入到所有构建流程，导致服务端构建、生产构建阶段也执行插桩逻辑，和Nuxt内置的转译规则、SSR构建逻辑冲突触发编译错误。
以下是经过验证可正常运行的配置方案，遵循仅客户端测试环境启用插桩的原则，完全避开编译冲突。 #

前置依赖安装 #

先安装对应开发依赖，注意版本匹配：

• Nuxt2项目：安装@cypress/code-coverage、babel-plugin-istanbul@6、cross-env、wait-on
• Nuxt3 + Vite项目：安装@cypress/code-coverage、vite-plugin-istanbul、cross-env、wait-on

安装命令示例：

# Nuxt2
npm i -D @cypress/code-coverage babel-plugin-istanbul@6 cross-env wait-on

# Nuxt3 + Vite
npm i -D @cypress/code-coverage vite-plugin-istanbul cross-env wait-on

Nuxt2 项目配置 #

1. 修改nuxt.config.js #

不要直接将istanbul插件写入全局babel配置，通过环境变量判断仅在Cypress测试的客户端构建阶段加载插件：

export default {
  // 其余业务配置保持不变
  build: {
    babel: {
      plugins: [
        // 仅测试环境+客户端构建时启用插桩
        ...(process.env.CYPRESS_COVERAGE === 'true' && process.client ? ['istanbul'] : [])
      ]
    },
    // 强制不转译node_modules内的文件，避免插桩第三方依赖触发报错
    transpile: []
  },
  // 新增覆盖率上报的中间件，接收Cypress运行时上报的覆盖率数据
  serverMiddleware: [
    ...(process.env.CYPRESS_COVERAGE === 'true' ? [{
      path: '/__coverage__',
      handler: (req, res) => {
        if (req.method !== 'POST') return res.end()
        let rawBody = ''
        req.on('data', chunk => rawBody += chunk)
        req.on('end', () => {
          global.__coverage__ = JSON.parse(rawBody)
          res.end('ok')
        })
      }
    }] : [])
  ]
}

2. 配置Cypress #

修改Cypress支持文件cypress/support/e2e.js（旧版本路径为cypress/support/index.js）：

import '@cypress/code-coverage/support'

修改Cypress配置文件cypress.config.js：

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      require('@cypress/code-coverage/task')(on, config)
      // 注入环境变量告知Nuxt启用覆盖率插桩
      process.env.CYPRESS_COVERAGE = 'true'
      return config
    }
  }
})

3. 添加运行脚本 #

在package.json的scripts段新增测试命令：

{
  "scripts": {
    "test:e2e:cov": "cross-env CYPRESS_COVERAGE=true nuxt dev & wait-on http://localhost:3000 && cypress run --env coverage=true"
  }
}

Nuxt3 项目配置 #

Nuxt3默认使用Vite构建，不要用babel-plugin-istanbul做插桩，会和Nitro服务端构建冲突，改用vite生态的插桩插件。

1. 修改nuxt.config.ts #

export default defineNuxtConfig({
  // 其余业务配置保持不变
  vite: {
    plugins: [
      ...(process.env.CYPRESS_COVERAGE === 'true' ? [
        require('vite-plugin-istanbul')({
          // 只插桩业务代码目录
          include: ['pages/**/*', 'components/**/*', 'composables/**/*', 'utils/**/*'],
          // 排除构建缓存、服务端代码、第三方依赖
          exclude: ['node_modules', '.nuxt', 'server/**/*', 'nitro.config.ts'],
          extension: ['.js', '.ts', '.vue'],
          cwd: process.cwd()
        })
      ] : [])
    ]
  }
})

2. Cypress配置 #

和上文Nuxt2的Cypress配置完全一致即可。

3. 运行脚本 #

和Nuxt2的脚本配置一致，注意如果Nuxt3启动端口不是3000，自行修改wait-on的地址即可。 #

常见报错排查 #

• 配置修改后先删除.nuxt缓存目录再重启服务，旧的编译缓存会导致新配置不生效
• 不要在生产构建、普通开发启动命令中携带CYPRESS_COVERAGE环境变量，插桩逻辑仅在跑Cypress测试时启用
• 如果出现语法类编译错误，检查插桩插件的exclude配置，确保没有将node_modules、自动生成的.nuxt目录、服务端代码纳入插桩范围
• 如果运行后覆盖率报告为空，检查是否在服务端构建阶段启用了插桩：服务端生成的覆盖率对象不会被Cypress采集，必须仅在客户端侧执行插桩
• 运行完测试后，覆盖率报告默认生成在coverage目录，打开lcov-report/index.html即可查看可视化报告

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