VSCode未打开setupTests.ts时无法识别Jest的setupFilesAfterEnv配置

问题背景 #

• 项目已通过jest.config.js的setupFilesAfterEnv指定根目录的setupTests.ts，该文件导入@testing-library/jest-dom以全局启用toBeInTheDocument()断言
• 配套独立的tsconfig.jest.json用于测试文件
• 仅VSCode存在异常：打开setupTests.ts时类型识别正常，关闭后所有使用该断言的测试代码报红：Property 'toBeInTheDocument' does not exist on type 'JestMatchers<HTMLElement>'.ts(2339)
• 重新打开setupTests.ts或临时重载VSCode可恢复，但重载后会突然失效；实际测试运行完全正常，仅IDE类型校验出问题

为啥会这样？ #

VSCode的TypeScript语言服务默认不会主动读取jest配置中指定的全局setup文件的类型扩展，只有当该文件处于打开状态时，才会加载其类型声明。

怎么解决？ #

方法1：给测试用tsconfig显式加类型声明 #

在tsconfig.jest.json的compilerOptions.types数组中添加@testing-library/jest-dom，强制TypeScript全局加载该类型：

{
  "compilerOptions": {
    // 你的其他配置...
    "types": ["jest", "@testing-library/jest-dom"]
  },
  // 其他配置...
}

方法2：创建全局类型声明文件 #

在项目根目录新建src/types/jest-dom.d.ts（任意.d.ts后缀文件均可），内容仅需一行：

import '@testing-library/jest-dom';

并确保该文件被tsconfig.json或tsconfig.jest.json的include字段覆盖：

{
  "include": ["src/**/*", "src/types/**/*.d.ts"]
}

方法3：切换VSCode的TS版本 #

确保VSCode使用项目本地的TypeScript版本（而非全局版本）：点击右下角的TS版本号，选择「Use Workspace Version」，避免全局版本与项目依赖不兼容导致的类型加载异常。

验证 #

配置完成后，关闭setupTests.ts并重启VSCode，检查测试文件中的toBeInTheDocument()是否仍能正常识别类型。

内容的提问来源于stack exchange，提问作者Daniel V.