TypeScript 中的 JSX 错误：--jsx 标志及其修复方法

「Cannot use JSX unless the '--jsx' flag is provided」——这是什么错误？

想象一下：您正满怀热情地用 TypeScript 编写您的第一个 React 应用程序。代码看起来完美，组件设计精良，斗志昂扬。您开始编译——然后突然看到这条冰冷、可怕的消息：

Cannot use JSX unless the '--jsx' flag is provided.

熟悉吗？别担心，您并不孤单。这个错误是 Stack Overflow 上最热门的问题之一，拥有数千次浏览量。但是，就像任何谜题一样，它有一个简单而优雅的解决方案。在本文中，我们不仅会修复这个错误，还会理解它为什么会出现，以及如何一劳永逸地配置 TypeScript 以处理 JSX。

顺便说一句，如果您刚刚开始您的 TypeScript 和 React 之旅，我建议您也查看我们关于 TypeScript 基础 的资料——这将帮助您在起步阶段避免许多陷阱。

为什么 TypeScript 会抱怨 JSX？

让我们来理解这个错误的本质。TypeScript 是一种严格的语言，默认情况下不理解类似 HTML 的 JSX 语法。当您编写：

const element = <h1>Hello, World!</h1>;

TypeScript 看到的不是熟悉的代码，而是陌生的东西。要向编译器解释这些尖括号不是错误，而是您 React 组件的一部分，需要显式指定 --jsx 标志。这就像给 TypeScript 一个翻译器：「听着，这些结构是有效的 JSX，不要动它们，要正确处理它们」。

这个错误在三种典型情况下出现：

\n
• 新项目——您忘记配置 tsconfig.json 以与 React 配合使用；
\n
• 从 JavaScript 迁移——您正在将项目转换为 TypeScript，但没有更新配置；
\n
• 使用 .tsx 文件——您创建了一个扩展名为 .tsx 的文件，但编译器不知道如何处理它。
\n

好消息：修复只需不到一分钟。坏消息：如果您不知道在哪里查找，可能会花费数小时。让我们一劳永逸地解决这个问题。

分步解决方案：配置 tsconfig.json

最正确且推荐的方法是将 JSX 设置添加到您的 tsconfig.json 中。这个文件是您 TypeScript 项目的大脑。正是在这里，我们将告诉编译器如何处理 JSX。

步骤 1：打开 tsconfig.json

在项目的根目录中找到 tsconfig.json 文件。如果没有，请创建它。可以使用以下命令：

npx tsc --init

此命令将生成一个包含许多注释选项的基本配置文件。不要害怕——我们只更改一行。

步骤 2：添加 jsx 选项

在 compilerOptions 对象内部，添加（或取消注释）这一行：

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // 其他设置...\n  }\n}

请注意：值 "react-jsx" 是 React 17+ 和 React 18 的现代标准。如果您使用的是旧版 React（17 之前），可以指定 "react"。但我强烈推荐 "react-jsx"——它生成更优化的代码，并且不需要在每个文件中导入 React。

步骤 3：保存并重新启动编译

保存更改后，错误应该消失。重新运行构建：

npm run build\n# 或\nnpx tsc

如果您操作正确，编译器将不再报错，您的应用程序将启动。

替代方法：面向高级用户

有时您需要快速验证一个假设或运行一个单文件脚本。在这种情况下，可以使用命令行标志：

npx tsc --jsx react-jsx app.tsx

这是一个临时解决方案——它不会更改项目的全局设置。