Next.js+TypeScript构建报'describe' is not defined错误如何解决

该报错触发逻辑非常明确：ESLint未识别测试文件中的Jest全局注入API，默认规则将describe/jest/it/expect这类Jest运行时自动注入的全局对象判定为未定义变量，触发no-undef规则拦截。
Next.js生产构建默认会对项目全量文件执行ESLint校验，只要测试文件在扫描范围内、且ESLint没有配置Jest环境识别，就会抛出这类错误。

按优先级从高到低选方案操作即可：

• 方案1：针对测试文件单独配置ESLint规则（推荐，无副作用）
  1. 先安装Jest对应的ESLint插件依赖：

     npm install -D eslint-plugin-jest
     # yarn用户执行：yarn add -D eslint-plugin-jest
     # pnpm用户执行：pnpm add -D eslint-plugin-jest
     

  2. 打开项目根目录的ESLint配置文件（后缀为.eslintrc.json/.eslintrc.js，或package.json中的eslintConfig字段），添加overrides配置，仅对测试文件开启Jest环境识别：

     {
       "overrides": [
         {
           "files": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"],
           "env": {
             "jest": true
           },
           "plugins": ["jest"],
           "extends": ["plugin:jest/recommended"]
         }
       ]
     }
     

     配置中"jest": true会自动将所有Jest官方全局API加入ESLint的识别白名单，从根源解决no-undef误报，且配置仅对测试文件生效，不会影响普通业务代码的校验规则。
• 方案2：手动声明Jest全局变量（无需额外装依赖，适合临时修复）
  如果不想新增插件依赖，可以直接在ESLint配置的globals字段中，声明项目用到的Jest全局变量为只读：

  {
    "globals": {
      "describe": "readonly",
      "it": "readonly",
      "test": "readonly",
      "expect": "readonly",
      "jest": "readonly",
      "beforeEach": "readonly",
      "afterEach": "readonly",
      "beforeAll": "readonly",
      "afterAll": "readonly"
    }
  }
  

  该方案的缺点是需要手动维护用到的Jest API列表，后续用到新的Jest全局方法时需要手动补充配置
• 方案3：构建阶段跳过测试文件的ESLint校验（适合测试文件有单独校验流程的场景）
  如果测试文件的校验已经在单独的测试CI流程中覆盖，不需要在Next.js生产构建时重复校验，可以直接将测试文件排除出构建时的ESLint扫描范围：
  1. 在项目根目录新建.eslintignore文件，添加以下规则：

     **/*.test.ts
     **/*.test.tsx
     **/*.spec.ts
     **/*.spec.tsx
     __tests__/**
     

  2. 也可以直接在next.config.js中配置ESLint扫描目录，仅指定需要校验的业务代码路径：

     /** @type {import('next').NextConfig} */
     const nextConfig = {
       eslint: {
         dirs: ['app', 'pages', 'components', 'lib', 'src']
       }
     }
     module.exports = nextConfig
     

所有配置修改完成后，重新执行npm run build验证构建结果即可，上述任意一种方案都可以解决当前的报错。

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