Cypress报错：cy.verifyDownload is not a function 问题求助

可能原因 #

• 配置PDF转HTML时，误删除或注释了cy-verify-downloads的自定义命令注册代码
• Cypress配置文件中，PDF转HTML的task配置覆盖了verifyDownloadTasks，导致插件未正确注册
• 依赖版本冲突：PDF转HTML相关依赖与cy-verify-downloads或Cypress版本不兼容
• 缓存残留：之前的插件安装缓存未清理，导致新配置未生效

解决步骤 #

1. 检查自定义命令注册
   打开cypress/support/e2e.js（或对应版本的入口文件，如index.js），确认存在以下代码：

   // CommonJS语法
   require('cy-verify-downloads').addCustomCommand();
   
   // 或ES模块语法
   import { addCustomCommand } from 'cy-verify-downloads';
   addCustomCommand();
   

   如果代码被删除或注释，恢复它，并确保放在PDF转HTML相关配置代码的后面，避免被覆盖。

2. 修复Cypress配置中的Task注册
   打开cypress.config.js，检查setupNodeEvents中的task配置：

   • 错误写法（会覆盖verifyDownloadTasks）：

     on('task', {
       // PDF转HTML的task配置
     });
     

   • 正确写法（合并task）：

     const { verifyDownloadTasks } = require('cy-verify-downloads');
     
     module.exports = defineConfig({
       e2e: {
         setupNodeEvents(on, config) {
           on('task', {
             ...verifyDownloadTasks,
             // 你的PDF转HTML相关task
           });
         },
       },
     });
     

3. 彻底清理依赖与缓存
   执行以下命令，清除残留的依赖和Cypress缓存：

   rm -rf node_modules package-lock.json
   npm install
   npx cypress cache clear
   

4. 验证版本兼容性
   确认cy-verify-downloads版本与当前Cypress版本匹配（例如Cypress 12.x+需搭配cy-verify-downloads 1.0.x+），同时检查PDF转HTML依赖的版本是否与现有插件兼容。

同类问题预防方案 #

• 修改Cypress配置或support目录下的文件前，先备份原文件，避免误删关键注册代码
• 新增第三方依赖后，先运行原有测试用例，验证插件功能是否正常
• 定期更新插件时，查看官方更新日志，确认是否有兼容性变更
• 将插件注册代码单独拆分到独立文件（如cypress/support/plugins-registry.js），再导入到入口文件，避免与其他配置代码混写导致覆盖

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