Cypress编写自定义命令时报'JQuery' is not defined ESLint错误

在VSCode中编辑cypress/commands.ts文件编写Cypress自定义命令时，使用JQuery类型会触发ESLint的no-undef规则报错，报错信息如下：

'JQuery' is not defined.eslint[no-undef]

从编辑器类型提示来看，JQuery类型实际存在，疑似存在重复同类型定义导致冲突。
编辑器类型提示截图
当前使用的Cypress版本为10.1.0

相关代码与配置 #

cypress/commands.ts 文件代码 #

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

declare global {
  namespace Cypress {
    interface Chainable {
      getElByAttr(attr: string, val: string): Chainable<JQuery<HTMLElement>>;
      getByTestId(testId: string, length?: number): Chainable<void>;
    }
  }
}

Cypress.Commands.add('getByTestId', (testId, length = 1) => {
  cy.get(`[data-testid="${testId}"]`).should('have.length', length);
});

Cypress.Commands.add('getElByAttr', (attr = 'name', val) => {
  return cy.get(`[${attr}=${val}]`);
});

export {};

根目录tsconfig.json配置 #

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "allowSyntheticDefaultImports": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitThis": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "incremental": true,
    "baseUrl": "."
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules", "babel.config.js", "jest.config.js", "__tests__/**/*.js"]
}

已尝试的修复操作 #

• 在/cypress目录下新增配置文件（文件名笔误为tsonfig.json），配置内容如下：

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress", "node"]
  },
  "include": ["**/*.ts"]
}

• 每次修改配置后均重启VSCode的TS服务，问题未解决
• 尝试在根目录tsconfig中添加"types": ["cypress"]配置
• 对照Cypress官方TypeScript支持文档、多个GitHub issue、Stack Overflow同类问题中的方案逐一尝试，均未修复问题

这个报错和TS类型缺失无关，核心原因是ESLint没有识别到Cypress内置的全局JQuery类型，加上之前cypress目录的TS配置文件名写错导致配置不生效，按以下步骤操作即可修复：

1. 先修正文件名笔误，把cypress目录下的tsonfig.json重命名为tsconfig.json。TS服务只会识别固定命名的配置文件，文件名写错的话，写的Cypress专属类型配置根本不会加载，还会导致根目录Next.js的TS配置和Cypress类型规则混杂引发冲突。
2. 两种方式处理ESLint的全局类型识别问题，二选一即可：
   • 方式一（推荐，一劳永逸）：打开项目的ESLint配置文件（支持.eslintrc/.eslintrc.js/.eslintrc.json格式），在globals字段中添加"JQuery": "readonly"，明确告诉ESLint这个类型是合法的全局变量，不需要显式导入。配置示例：

     {
       "globals": {
         "JQuery": "readonly"
       }
     }
     

   • 方式二（单文件快速修复）：直接在cypress/commands.ts文件最顶部添加一行ESLint全局声明注释，放在三斜杠类型引用之前即可：

     /* global JQuery */
     /// <reference types="cypress" />
     // 原有剩余代码保持不变
     

3. 不要在根目录的tsconfig.json里添加"types": ["cypress"]配置，这个操作会覆盖TS默认的类型加载逻辑，把Cypress的测试类型注入到所有业务代码中，反而会引发页面、组件文件的类型报错。Cypress相关的TS配置必须放在cypress目录下的独立tsconfig.json中，和根目录的项目配置做隔离。
4. 所有配置修改完成后，在VSCode中分别执行「重启ESLint服务」「重启TypeScript服务」操作即可生效，不需要额外安装@types/jquery依赖，Cypress 10.1.0版本本身已经内置了对应的JQuery类型定义。

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