Vite创建的React+TypeScript项目类型检查失效，如何排查？

问题背景 #

我用Vite创建了一个基于TypeScript的React应用，但类型检查功能突然失效了，还找不到之前正常工作的提交版本。
示例报错：
Cannot find module 'react' or its corresponding type declarations.
或
Cannot find module '/vite.svg' or its corresponding type declarations.（该文件是public文件夹里的默认svg）

可尝试哪些检查来定位问题？

相关配置文件 #

vite.config.ts（所有导入都标记“找不到类型定义”错误）

/// <reference types="vitest" />
/// <reference types="vite/client" />

import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './src/utils/test-setup.ts',
  },
})

tsconfig.json（存在Cannot find type definition file for 'vitest/globals'错误）

{
  "compilerOptions": {
    "target": "ESNext",
    "useDefineForClassFields": true,
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "allowJs": false,
    "skipLibCheck": true,
    "esModuleInterop": false,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "types": ["vitest/globals"]
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

package.json依赖（yarn dev/yarn test可正常运行）

"dependencies": {
  "mui": "^0.0.1",
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "react-query": "^3.39.3",
  "react-router-dom": "^6.9.0"
},
"devDependencies": {
  "@testing-library/dom": "^9.2.0",
  "@testing-library/jest-dom": "^5.16.5",
  "@testing-library/react": "^14.0.0",
  "@testing-library/user-event": "^14.4.3",
  "@types/react": "^18.0.28",
  "@types/react-dom": "^18.0.11",
  "@types/testing-library__jest-dom": "^5.14.5",
  "@vitejs/plugin-react": "^3.1.0",
  "@vitest/coverage-c8": "^0.29.7",
  "@vitest/ui": "^0.29.7",
  "jsdom": "^21.1.1",
  "typescript": "^4.9.3",
  "vite": "^4.2.0",
  "vitest": "^0.29.7"
}

排查步骤 #

1. 重启TypeScript服务并清理缓存 #

• 在编辑器（如VS Code）中打开命令面板，执行TypeScript: Restart TS Server，多数类型检查异常是服务缓存导致的。
• 删除项目根目录下的.tsbuildinfo文件（若存在），清除TS增量编译缓存。

2. 修正tsconfig.json的类型配置 #

• 当前types字段仅包含vitest/globals，会覆盖默认类型集合，导致React、Vite客户端类型无法被识别。修改为：

  "types": ["vite/client", "vitest/globals"]
  

• 确认tsconfig.node.json存在且配置正常，因为主tsconfig引用了该文件，缺失或错误会影响类型检查。

3. 解决SVG等资源的类型声明问题 #

• 针对/vite.svg的报错，在src目录创建vite-env.d.ts文件，添加SVG类型声明：

  declare module '*.svg' {
    const content: string;
    export default content;
  }
  

• 确保vite.config.ts中的/// <reference types="vite/client" />被正确识别，该引用已包含Vite对SVG等资源的类型定义，同时要保证tsconfig的include范围覆盖了vite.config.ts。

4. 重新安装依赖并验证类型包完整性 #

• 执行yarn install --force强制重新安装所有依赖，修复可能损坏的类型文件。
• 检查@types/react、@types/react-dom与对应库版本的兼容性（当前版本匹配，也可尝试升级到最新@types包）。

5. 调整tsconfig的include范围 #

• 当前include仅包含src，但vite.config.ts不在范围内，导致TS无法识别其类型。修改为：

  "include": ["src", "vite.config.ts"]
  

• 确认测试配置文件（如test-setup.ts）也在include范围内，避免类型检查遗漏。

6. 修复Vitest全局类型报错 #

• 针对Cannot find type definition file for 'vitest/globals'，可尝试在types字段添加vitest：

  "types": ["vite/client", "vitest", "vitest/globals"]
  

• 在vite-env.d.ts中添加/// <reference types="vitest" />，确保Vitest类型被正确加载。

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