React Testing Library 与 Vitest 集成中的模块导入问题解析

在使用 React Testing Library 进行组件测试时，许多开发者正从 Jest 转向 Vitest 测试框架。本文将以一个典型问题为例，深入分析当两者结合使用时可能遇到的模块导入错误及其解决方案。

问题现象

当开发者配置了以下技术栈时：

• Vitest 1.3.1 作为测试框架
• @testing-library/react 14.2.1 进行组件测试
• React 18.2.0 和 React DOM 18.2.0
• PNPM 8.14.0 作为包管理器

运行测试时会遇到错误提示：

SyntaxError: Cannot use import statement outside a module

错误指出 React DOM 的测试工具文件似乎是一个 ES 模块，但却被打包在 CommonJS 包中。

技术背景分析

这个问题本质上源于现代 JavaScript 模块系统与旧有 CommonJS 模块系统的兼容性问题。Vitest 作为基于 Vite 的测试框架，默认采用 ES 模块规范，而 React DOM 的某些测试工具文件仍保持 CommonJS 格式。

配置要点

正确的 TypeScript 配置应包含以下关键设置：

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "target": "ES6",
    "module": "esnext",
    "esModuleInterop": true,
    "moduleResolution": "node"
  }
}

Vitest 配置文件中需要确保正确加载 React 插件和路径解析：

import react from "@vitejs/plugin-react-swc"
import { defineConfig } from "vitest/config"

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom"
  }
})

解决方案

经过实践验证，最有效的解决方法是：

1. 彻底清理 node_modules：使用 PNPM 时，有时残留的旧版本依赖会导致兼容性问题。执行 pnpm install --force 或完全删除 node_modules 后重新安装。

2. 检查模块类型声明：确保 package.json 中正确指定了 "type": "module"（如果使用 ES 模块）。

3. 验证测试环境：确认 Vitest 配置中正确设置了 jsdom 测试环境。

4. 检查文件扩展名：确保测试文件使用 .ts 或 .tsx 扩展名，Vitest 能正确处理这些文件类型。

最佳实践建议

1. 保持依赖更新：定期更新测试相关依赖，特别是 React Testing Library 和 Vitest，以获得最好的兼容性。

2. 统一模块系统：在项目中明确模块系统规范，避免混合使用 ES 模块和 CommonJS。

3. 使用标准化导入：在测试文件中，统一使用 ES 模块的 import 语法。

4. 配置隔离：为测试环境单独配置 TypeScript 和 Vitest，避免与生产构建配置冲突。

通过理解模块系统的工作原理和正确配置测试环境，开发者可以顺利地在 Vitest 中使用 React Testing Library 进行组件测试，享受 Vitest 带来的快速测试体验。