修复React应用中“jsx”必须在作用域内错误的指南

本文旨在解决React应用中常见的“’jsx’ must be in scope”错误。该错误通常源于JSX编译指示（Pragma）的误用，特别是当开发者试图自定义JSX转换函数（如使用/** @jsx jsx */）而未正确导入相应的函数时。文章将深入探讨JSX编译原理，并提供两种核心解决方案：为自定义JSX运行时（如Emotion）导入jsx函数，或移除不必要的编译指示以恢复React默认的JSX转换行为，确保应用能够正确编译和运行。

理解JSX编译指示与作用域错误

在react应用开发中，当您遇到“’jsx’ must be in scope when using jsx”或“jsx is not defined”的错误时，这通常与jsx的编译方式有关。jsx（javascript xml）是一种语法糖，它允许我们在javascript代码中编写类似html的结构。然而，浏览器并不能直接理解jsx，它需要被babel等工具转换成标准的javascript函数调用。

默认情况下，Babel会将JSX元素（例如<MyComponent />）转换为React.createElement()函数调用。这意味着在旧版React中，您需要在每个使用JSX的文件顶部导入import React from ‘react’;，以确保React.createElement在作用域内。

// 默认转换示例 (React 16及以前)
// <MyComponent />
// 转换为
// React.createElement(MyComponent, null)

然而，React 17引入了新的JSX转换机制（New JSX Transform），它不再需要显式导入React对象来使用JSX。在新的转换模式下，Babel会根据需要自动导入特殊的_jsx或_jsxs函数，这些函数通常来自react/jsx-runtime。

// 新的JSX转换示例 (React 17及以后)
// <MyComponent />
// 转换为
// import { jsx as _jsx } from "react/jsx-runtime";
// _jsx(MyComponent, {})

问题根源：`/ @jsx jsx */` 编译指示**

当您在文件顶部看到/** @jsx jsx */这样的注释时，它是一个JSX编译指示（Pragma）。这个指示会告诉Babel的JSX转换插件，不要使用默认的React.createElement（或新的_jsx函数），而是使用一个名为jsx的自定义函数来编译JSX表达式。这在某些库中非常常见，例如Emotion，它使用自定义的jsx函数来处理其css prop。

如果您使用了/** @jsx jsx */指示，但没有在文件中导入名为jsx的函数，那么当Babel将JSX转换为jsx()调用时，运行时就会抛出jsx is not defined的错误。ESLint的react/react-in-jsx-scope规则也可能会因此发出警告，因为它认为jsx应该在作用域内。仅仅禁用ESLint规则并不能解决根本的编译错误，因为这只是隐藏了问题，而不是解决了它。

解决方案一：导入自定义JSX函数（适用于Emotion等库）

如果您正在使用像Emotion这样的库，并且需要利用其特定的功能（例如css prop），那么使用/** @jsx jsx */编译指示是正确的。在这种情况下，您需要确保从相应的库中导入jsx函数。

示例代码：

/** @jsx jsx */ // 明确告知Babel使用名为jsx的函数进行JSX转换
import { createContext, useContext, useState } from 'react';
import { jsx } from '@emotion/react'; // 关键：从Emotion导入jsx函数
interface MyContextType {
isReady: boolean;
}
interface Props {
children: React.ReactNode;
}
const MyContext = createContext({} as MyContextType);
export const MyContextProvider = ({ children }: Props) => {
const [isReady, setIsReady] = useState(false);
return (
// 在这里，<MyContext.Provider> 会被Emotion的jsx函数处理
<MyContext.Provider value={{ isReady }}>
{children}
</MyContext.Provider>
);
};
// 如果您还使用了Emotion的css prop，它将正常工作
const MyStyledComponent = () => (
<p
css={{
color: 'blue',
fontSize: '16px',
}}
>
这是一个Emotion样式化的段落。
</p>
);

注意事项：

• 确保您已正确安装并配置了Emotion库（或任何其他需要自定义JSX运行时的库）。
• import { jsx } from ‘@emotion/react’; 这一行是解决此问题的核心。
• 即使您没有直接使用Emotion的css prop，但文件中有/** @jsx jsx */，也需要导入jsx。

解决方案二：移除不必要的JSX编译指示（恢复默认行为）

如果您没有使用Emotion或其他需要自定义JSX编译器的库，那么/** @jsx jsx */编译指示就是多余的，并且会导致错误。在这种情况下，最简单的解决方案就是移除它。

当您移除/** @jsx jsx */时，Babel将恢复其默认的JSX转换行为。

• 对于React 17+项目（使用新的JSX转换）： Babel会自动处理JSX到_jsx或_jsxs函数的转换，您甚至不需要在文件顶部导入React对象来使用JSX（尽管您可能仍然需要导入React来使用React.useState、React.useEffect等钩子）。
• 对于React 16及以前的项目（使用经典JSX转换）： Babel会将JSX转换为React.createElement()。因此，您仍然需要import React from ‘react’;来确保React.createElement在作用域内。

示例代码：

// 移除 /** @jsx jsx */ 这一行
import { createContext, useContext, useState } from 'react';
// import React from 'react'; // 在React 17+中，如果只使用JSX，可以省略此行，但如果使用hooks等，仍需导入
interface MyContextType {
isReady: boolean;
}
interface Props {
children: React.ReactNode;
}
const MyContext = createContext({} as MyContextType);
export const MyContextProvider = ({ children }: Props) => {
const [isReady, setIsReady] = useState(false);
return (
// 现在，<MyContext.Provider> 将被默认的React JSX转换处理
<MyContext.Provider value={{ isReady }}>
{children}
</MyContext.Provider>
);
};

注意事项：

• 这是解决大多数此类问题的首选方法，除非您明确知道自己需要一个自定义的JSX运行时。
• 在React 17+项目中，即使移除了/** @jsx jsx */，您也可能需要导入React来使用其提供的钩子（如useState, useEffect等）。

总结

“’jsx’ must be in scope”错误的核心在于JSX编译指示与实际导入的JSX转换函数不匹配。解决此问题需要根据您的项目需求进行判断：

1. 如果您的项目确实使用了Emotion或其他需要自定义JSX运行时的库，并且您希望利用其特殊功能，那么请保留/** @jsx jsx */编译指示，并确保从相应的库中导入jsx函数（例如import { jsx } from ‘@emotion/react’;）。
2. 如果您的项目没有使用自定义JSX运行时，或者您不希望使用其特殊功能，那么最直接的解决方案是移除文件顶部的/** @jsx jsx */编译指示。这将使Babel恢复默认的React JSX转换行为，从而消除错误。

理解JSX编译的底层机制和不同版本的React/Babel如何处理JSX，是高效解决这类问题的关键。在开发过程中，务必保持对项目依赖和配置的清晰认识。