React 项目中解决 "Type 'Element' is not assignable to type 'ReactNode'" 错误

使用 Vite 创建 React + TypeScript 应用时，常见以下错误：

Type 'Element' is not assignable to type 'ReactNode'.
Type 'Element' is not assignable to type 'ReactPortal'.

该错误通常出现在 VS Code 编辑器中，但浏览器运行时一切正常。问题根源在于 React 类型声明不匹配或 TypeScript 配置不当。下面是经过验证的解决步骤：

🚫 常见错误原因

1. 过时的 @types/react 或 @types/react-dom（最常见）
2. TypeScript 配置未针对 Vite 优化
3. Vue 中缺少必要的配置项（如 compilerOptions.lib）

✅ 最佳解决方案

1. 更新 React 类型声明（推荐）

在项目中执行：

# npm
npm update @types/react@latest @types/react-dom@latest -D

# yarn
yarn upgrade @types/react@latest @types/react-dom@latest -D

# pnpm
pnpm update @types/react@latest @types/react-dom@latest -D

关键：确保 @types/react 和 @types/react-dom 的版本与 react/react-dom 版本兼容。检查 package.json：

{
  "devDependencies": {
    "@types/react": "^18.2.25", // 推荐 ≥18.2.25
    "@types/react-dom": "^18.2.13"
  }
}

2. 正确配置 tsconfig.json

Vite 项目需要使用特定配置：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler", // Vite 必需配置
    "lib": ["DOM", "DOM.Iterable", "ESNext"], // 必须包含"DOM"
    "jsx": "react-jsx",
    "strict": true, // 建议保持开启
    "skipLibCheck": true
  },
  "include": ["src"]
}

特别注意

moduleResolution: "Bundler" 是 Vite 项目的关键配置！旧版常用的 node_modules 解析方式不适用于 Vite

3. 重新安装类型定义

如更新无效，可重新安装：

npm uninstall @types/react @types/react-dom
npm install @types/react@latest @types/react-dom@latest -D

重启 VS Code 或执行 Reload Window 操作

4. 清除 VS Code 缓存

1. 打开命令面板 (Ctrl+Shift+P)
2. 选择 Developer: Reload Window
3. 或直接删除缓存：
   • Windows: %APPDATA%\Code\Cache
   • macOS: ~/Library/Application Support/Code/Cache
   • Linux: ~/.config/Code/Cache

🛠 备用方案

修复依赖冲突

npm audit fix --force
# 或
yarn upgrade-interactive

React 版本锁定（极端情况）

若问题仅在特定版本存在，在 package.json 中添加：

{
  "overrides": {
    "@types/react": "18.2.25"
  }
}

不推荐做法

禁用严格模式的“解决方案”（"strict": false 或 "skipLibCheck": true）会带来更大风险，它：

• 隐藏潜在的类型问题
• 使项目失去 TypeScript 的主要优势

📌 总结步骤

1. 更新 @types/react 和 @types/react-dom
2. 确认 tsconfig.json 包含 "moduleResolution": "Bundler"
3. 检查 lib 字段包含 "DOM"
4. 重载 VS Code 窗口或清除缓存
5. 重启开发服务器

此问题的核心在于类型系统一致性。遵循上述步骤能解决 95% 以上的类似错误，同时保持代码的类型安全性。如问题仍存，请检查项目依赖树：

npm list @types/react
# 或
yarn why @types/react