React 引用 UMD 全局变量，但当前文件是模块

当你在 TypeScript 项目中遇到 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.ts(2686) 错误时，这通常意味着 TypeScript 编译器无法找到 React 的声明。本文将为你详细解释这个问题的原因和多种解决方案。

问题背景

自从 React 17 引入了新的 JSX 转换功能后，开发者不再需要在每个文件中显式导入 React。然而，在 TypeScript 环境中，如果配置不正确，你可能会遇到上述错误。

考虑以下简单的 TSX 文件：

const Users = () => {
    return <>Teachers aka Users</>;
};

export default Users;

虽然这段代码在 Babel 中可能正常工作，但 TypeScript 会报错，因为它需要明确知道 JSX 元素的类型定义。

解决方案

1. 配置 TypeScript 支持新的 JSX 转换（推荐）

确保你的项目满足以下条件：

• TypeScript 版本至少为 4.1
• React 和 React-DOM 版本至少为 17
• tsconfig.json 中的 jsx 编译器选项设置为 react-jsx

{
  "compilerOptions": {
    // ...其他配置
    "jsx": "react-jsx"
  }
}

INFO

对于开发环境，你还可以使用 "jsx": "react-jsxdev" 选项，它提供额外的调试功能。

2. 包含所有必要的文件

确保你的 tsconfig.json 包含了所有 TypeScript 和 JSX 文件：

{
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.js",
    "src/**/*.jsx",
    ".storybook/*" // 如果你使用 Storybook
  ]
}

3. 使用正确的 ECMAScript 目标

确保你的 TypeScript 配置使用适当的 ES 目标版本：

{
  "compilerOptions": {
    "target": "es2015", // 至少需要 ES2015
    // ...其他配置
  }
}

4. Vite 项目特定配置

如果你使用 Vite，确保在正确的配置文件中设置 JSX：

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

5. 重启 TypeScript 服务器

在 VS Code 中，有时只需重启 TypeScript 服务器即可解决此问题：

1. 打开命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)
2. 输入 "TypeScript: Restart TS server"
3. 选择该命令执行

VS Code 设置调整

如果你在 JavaScript 文件中遇到此问题，检查以下设置：

{
  "js/ts.implicitProjectConfig.checkJs": false
}

6. 使用 Babel 进行转换

对于自定义 Webpack 配置，确保正确设置 Babel：

module.exports = {
  presets: [
    ["@babel/preset-react", {
      "runtime": "automatic" // 启用新的 JSX 转换
    }]
  ]
};

7. 备用方案：显式导入 React

如果以上方法都不适用，你可以回退到传统的导入方式：

import React from 'react';

const Users: React.FC = () => {
    return <>Teachers aka Users</>;
};

export default Users;

常见陷阱和注意事项

1. 文件位置：确保你的文件不在项目根目录，而是在 src 文件夹内
2. 文件命名：避免使用 index.ts 作为组件文件名，使用标准的命名约定
3. TypeScript 版本：在 VS Code 中，确保使用工作区内的 TypeScript 版本而非内置版本
4. 非 TypeScript 项目：对于纯 JavaScript 项目，创建 jsconfig.json 或调整 VS Code 设置

WARNING

不要通过将 "strict": false 来禁用严格模式来解决此问题，这会隐藏其他潜在的类型错误。

总结

'React' refers to a UMD global 错误通常是由于 TypeScript 配置不正确导致的。最佳解决方案是配置 TypeScript 以支持 React 17+ 的新 JSX 转换功能，通过设置 "jsx": "react-jsx" 并确保项目满足其他先决条件。

这些解决方案应该能帮助你解决 TypeScript 中的 React UMD 全局引用错误，让你能够充分利用 React 17+ 的新特性而无需在每个文件中显式导入 React。