Next.js集成Cypress覆盖率时全局命名空间声明报错

问题概述 #

在Next.js项目中使用Cypress做代码覆盖率时，自定义的mount和dataCy命令类型声明未生效，在cypress/support/component.ts中添加mount命令时出现TS报错：

Argument of type '"mount"' is not assignable to parameter of type 'keyof Chainable'.ts(2345)
期望"mount"已存在。

怀疑Cypress未使用项目根目录的tsconfig.json，而是读取自身默认配置。

解决方案 #

1. 修正类型声明文件（cypress.d.ts） #

重复声明Cypress命名空间会导致TS无法正确合并接口，同时需要引入cypress/react18的类型以解析mount的类型：

/// <reference types="cypress" />
/// <reference types="cypress/react18" />

declare namespace Cypress {
  interface Chainable {
    /**
     * 自定义命令：挂载React组件
     */
    mount: typeof import('cypress/react18').mount;
    
    /**
     * 自定义命令：通过data-cy属性选择DOM元素
     * @example cy.dataCy('greeting')
     */
    dataCy(value: string): Chainable<Element>;
  }
}

2. 让Cypress使用项目的tsconfig #

在cypress.config.ts中显式指定TS配置文件路径，覆盖Cypress默认配置：

import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
    typescript: {
      tsConfig: './tsconfig.json', // 指定项目根目录的tsconfig
    },
  },
  // 若有E2E测试，同样配置
  e2e: {
    typescript: {
      tsConfig: './tsconfig.json',
    },
  },
});

3. 优化tsconfig.json的include配置 #

移除不必要的node_modules/cypress（会导致类型冲突），确保Cypress相关文件被正确包含：

{
  "compilerOptions": {
    // 保持原有配置不变
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    "./cypress.d.ts",
    "cypress/**/*.ts",
    "cypress/**/*.tsx"
  ],
  "exclude": ["node_modules"],
  "ts-node": {
    "compilerOptions": {
      "module": "ESNext",
      "moduleResolution": "Node"
    }
  }
}

4. 重启TS服务 #

修改配置后，重启编辑器的TypeScript服务（比如VSCode中按Ctrl+Shift+P，选择「TypeScript: Restart TS Server」），确保类型更新生效。

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