配置Cypress代码覆盖率后仅检测到单测覆盖、未生成报告如何解决

你遇到的“仅检测到单元测试覆盖率”的提示，核心原因是Cypress执行过程中没有从被测的前端页面中采集到有效覆盖率埋点数据，仅检索到了目录下遗留的单元测试覆盖率文件，导致最终聚合时没有足够的Cypress维度样本，无法生成可查看的覆盖率报告，可按以下顺序逐一排查：

插件注册链路完整性核查 #

• 确认cypress/support目录下的入口文件（新版为e2e.js，老版本为index.js）中，已经引入了覆盖率插件的support文件：import '@cypress/code-coverage/support'，缺少这行的话，测试执行时页面采集到的覆盖率数据根本不会回传给Cypress主进程
• 确认cypress.config.js（老版本为cypress/plugins/index.js）中的插件注册逻辑无遗漏：

  正确注册写法需在setupNodeEvents回调中引入任务注册，并正确返回处理后的config对象：

  // cypress.config.js 配置片段
  const { defineConfig } = require('cypress')
  
  module.exports = defineConfig({
    e2e: {
      setupNodeEvents(on, config) {
        // 注册覆盖率插件任务
        require('@cypress/code-coverage/task')(on, config)
        // 其他自定义插件逻辑
        return config
      },
    },
  })
  

• 重点排查项：不少人配置时容易漏掉setupNodeEvents末尾的return config，导致Cypress无法加载插件注入的覆盖率采集相关配置，从根源上无法触发数据采集

babel-plugin-istanbul的转换范围核查 #

• 确认babel配置（babel.config.js或.babelrc）中的babel-plugin-istanbul配置，没有把被测的业务源码路径排除：很多项目在配置插件时，直接复用了单元测试的exclude规则（排除**/*.cy.js、**/*.spec.js），但没有覆盖到所有需要统计覆盖率的业务源码（比如src/目录下的js、ts、vue文件），导致源码没有被注入埋点
• 确认本地启动前端dev服务时，加载的是带babel-plugin-istanbul的配置：不少人启动服务时用的是生产环境babel配置，完全没有引入istanbul插件，这种情况下页面加载的代码本身没有任何覆盖率埋点，Cypress自然采集不到有效数据
• 构建链路避坑：如果项目用Vite、Rspack这类现代构建工具，不能仅靠babel配置生效：这类工具的预构建、esbuild转译链路会绕过部分babel转换逻辑，需要搭配对应构建工具的istanbul插件，才能确保源码被正确注入埋点

遗留缓存清理与干扰排除 #

• 提示语“Only found unit test code coverage”的本质，是Cypress在扫描覆盖率数据时，仅找到了.nyc_output缓存目录、coverage输出目录下之前单元测试生成的历史文件，没有采集到本次Cypress执行时浏览器回传的新数据
• 对应操作：
  • 直接删除项目根目录下的coverage文件夹，以及隐藏的.nyc_output缓存文件夹，清除历史遗留的旧覆盖率文件
  • 无缓存重启前端dev服务，同时清空浏览器加载缓存，避免旧的无埋点代码被重复加载
  • 重新执行测试过程中观察控制台日志，正常采集时会输出类似“从浏览器采集到N份覆盖率样本”的提示，如果完全没有这类输出，说明埋点没有注入成功

特殊场景配置补全 #

• 如果Cypress测试是跨域访问前端dev服务的，需要确认跨域权限配置允许页面回传覆盖率数据，否则埋点数据会被浏览器跨域策略拦截，无法传回Cypress主进程
• 如果项目是TypeScript技术栈，需要确认ts代码的编译链路没有绕过babel转换，避免esbuild、tsc直接编译输出无埋点的代码
• 检查是否给覆盖率插件传了错误的输出路径参数，避免生成的报告文件被写到了不存在、或被gitignore排除的目录下，造成“没有生成报告”的误判

内容的提问来源于stack exchange，提问作者Gašper Štepec