修复“Expression produces a union type that is too complex to represent.ts(2590)”错误

问题背景

在使用 @chakra-ui/react 的 Button 组件时，TypeScript 抛出 ts(2590) 错误，提示联合类型过于复杂无法表示：

import { Button } from "@chakra-ui/react";

function Page() {
  return <Button onClick={(event) => {}}>Text</Button>; // 报错位置
}

该错误通常发生在 TypeScript 类型系统无法处理过于复杂的联合类型推断时，常见原因包括：

• VSCode 使用了错误版本的 TypeScript
• TypeScript 5.x 与 UI 库的兼容性问题
• tsconfig.json 中 jsxImportSource 的不当配置

核心解决方案

优先尝试

以下解决方案已帮助多数开发者解决问题，按推荐强度排序

1. 确保 VSCode 使用项目中的 TypeScript 版本

这是最高效的首选解决方案（328 个赞同）

your-project/
├── node_modules/
│   └── typescript/ # 确保已安装
├── package.json

配置步骤：

1. 在 VSCode 中打开一个 .ts 或 .tsx 文件
2. 执行以下任一操作：
   • 点击 VSCode 底部状态栏的 TypeScript 版本号
   • 按下 Ctrl+Shift+P 打开命令面板，搜索 "TypeScript: Select TypeScript Version"
3. 选择 "Use Workspace Version"

VSCode 设置配置

如果看不到该选项，在 .vscode/settings.json 中添加：

{
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "typescript.tsdk": "node_modules/typescript/lib"
}

重启 VSCode 后会自动提示激活工作区版本

2. 更改 TypeScript 版本

若更新 VSCode 配置无效（20 个赞同）

{
  "devDependencies": {
-    "typescript": "^5.0.0",
+    "typescript": "^4.9.5"
  }
}

执行以下命令完成降级：

# 清除缓存重新安装
rm -rf node_modules package-lock.json
npm install
# 或
yarn install

3. 移除 tsconfig.json 中的 Emotion 配置

特别适用于 NX 项目初始化时选择了 Emotion（14 个赞同）

{
  "compilerOptions": {
-   "jsxImportSource": "@emotion/react"
  }
}

如果确实需要使用 Emotion，添加类型声明：

{
  "compilerOptions": {
    "types": [
      "react",
      "@emotion/react/types/css-prop" 
    ]
  }
}

4. 升级 Chakra UI 版本

修复库本身兼容性问题（社区验证）

npm upgrade @chakra-ui/react@latest
# 或指定版本
npm install @chakra-ui/react@2.5.5

备选解决方案

临时绕过方案

在无法立即解决根本问题时可以使用（谨慎使用）

<Button 
  css=""  // 添加空CSS属性绕过类型推断
  onClick={(e) => console.log(e)}
>
  Click
</Button>

import { Button } from "@chakra-ui/react";

function Page() {
  return (
    <>
      {/* @ts-ignore */}
      <Button onClick={(event) => {}}>Text</Button>
    </>
  );
}

验证解决方案

安装完成后执行类型检查：

npx tsc --noEmit

如果输出中没有 ts(2590) 错误提示，说明问题已解决。

总结问题原因

此错误通常由以下组合导致：

1. TypeScript 版本冲突：VSCode 默认使用内置新版 TS，而项目使用旧版
2. 类型定义过载：Chakra UI 的复杂类型系统+TS 5.x内部优化问题
3. JSX 配置冲突：特别是与 Emotion 等 CSS-in-JS 库共同使用时

💡 推荐解决路径：
1 → 3 → 2 → 库升级 → 临时方案

更新于：2024年3月 | 验证环境：TypeScript 5.0+, Chakra UI 2.5+