新建Vite React TypeScript项目出现TS错误如何解决？

开发者阿泽

2026-7-12

修复Vite TypeScript + SWC React项目的"Cannot find module 'react/jsx-runtime'"错误

检查@types/react与@types/react-dom版本匹配性
版本不兼容是常见诱因，执行yarn list @types/react @types/react-dom查看版本，若两者版本不一致，执行yarn add @types/react@latest @types/react-dom@latest -D统一版本。
清理缓存并重装依赖
缓存异常可能导致依赖加载错误，执行以下操作：
```
# macOS/Linux
rm -rf node_modules yarn.lock
# Windows
rmdir /s /q node_modules && del yarn.lock
```
之后重新执行yarn install。

校验tsconfig.json完整配置
确保compilerOptions包含以下关键配置，且结构完整：

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

同时确认项目根目录下存在tsconfig.node.json，配置如下：

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts"]
}

切换VSCode的TypeScript版本
VSCode内置TS版本可能与项目本地版本冲突，打开命令面板（Ctrl+Shift+P），输入TypeScript: Select TypeScript Version，选择Use Workspace Version。
临时添加类型声明（极端情况）
若以上方案均无效，在src目录下创建react-jsx.d.ts文件，内容如下：
```
declare module 'react/jsx-runtime' {
  export default any;
}
```
此为临时兜底方案，建议优先排查根本问题。