eslint-plugin-react 的 react-in-jsx-scope 规则详解：JSX 语法下的 React 作用域检查

开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载react-in-jsx-scope是 eslint-plugin-react 中用于在 JSX 语法下检查React或自定义 JSX pragma变量是否处于作用域内的核心规则。它解决的是写了 JSX 却忘了引入 React这一在旧版 JSX 编译模型中极易出现的运行时错误。读完本文你将掌握该规则的触发条件、正确的修复方式、jsxpragma 的定制用法、与 React 17/19 新 JSX transform 的协作方式以及它在仓库源码中的完整实现原理。规则背景为什么 JSX 需要 React 在作用域中在 React 17 之前JSX 只是一种语法糖a /在编译时会被展开为React.createElement(a)。这意味着无论代码中是否直接使用了React标识符只要写了 JSXReact变量就必须存在于当前作用域中否则编译产物会在运行时抛出ReferenceError: React is not defined。react-in-jsx-scope规则正是针对这一约束设计的它遍历 JSX 语法节点检查 JSX 展开后所依赖的变量是否已经通过import、require或其他方式声明。规则的定义位于 lib/rules/react-in-jsx-scope.js作者为 Glen Mailer归属于Possible Errors可能错误类别meta.docs.recommended为true。规则详情何时报错、何时放行不正确的代码示例场景一使用了 JSX但完全没有声明React变量var Hello divHello {this.props.name}/div;场景二声明了React但文件中的jsx注解指定了其他 pragma此时规则检查的是注解指定的变量而非React/** jsx Foo.bar */ var React require(react); var Hello divHello {this.props.name}/div;第二段代码报错的原因在于jsx Foo.bar告诉编译器用Foo.bar替代React.createElement因此规则改为检查Foo是否在作用域中而声明React是无济于事的。正确的代码示例方式一ES Module 导入import React from react; var Hello divHello {this.props.name}/div;方式二CommonJS 引入var React require(react); var Hello divHello {this.props.name}/div;方式三使用自定义 pragma 时声明对应的变量/** jsx Foo.bar */ var Foo require(foo); var Hello divHello {this.props.name}/div;可以看到规则并不关心React/Foo是如何进入作用域的——import、require、var声明等任何一种方式都能通过检查。这与测试用例中var React, App; App /;、import React from react/addons; ...等valid用例相互印证见 tests/lib/rules/react-in-jsx-scope.js。报错信息当检查失败时规则通过report工具输出如下消息模板定义于 lib/rules/react-in-jsx-scope.js{{name}} must be in scope when using JSX其中{{name}}会被替换为当前生效的 pragma 名称默认是React自定义后是Foo等以便开发者一眼定位缺失的变量。如何配置与启用通过recommended预设开启该规则在recommended共享配置中是启用的且严重级别为 error。其配置定义在 index.jsreact/react-in-jsx-scope: SEVERITY_ERROR,因此在旧版 JSX 编译模式下只需在你的 ESLint 配置中extends预设即可生效{ extends: [plugin:react/recommended] }使用 ESLint 9 的 flat config 时可引入 flat 版本const reactRecommended require(eslint-plugin-react/configs/recommended); module.exports [ { plugins: { react: require(eslint-plugin-react) }, ...reactRecommended, }, ];flat 版本由 configs/recommended.js 提供它复用了 legacy 预设的规则与parserOptionsecmaFeatures.jsx: true并通过Object.defineProperty将languageOptions设为不可枚举以兼容 ESLint 的配置合并逻辑。通过jsx-runtime预设关闭如果你使用了 React 17 引入的新 JSX transform即react/jsx-runtime自动导入模式编译器不再依赖React在作用域中此时应当关闭本规则同时关闭配套的 react/jsx-uses-react。仓库在 index.js 中内置了jsx-runtime预设明确将这两条规则设为SEVERITY_OFF{ extends: [plugin:react/jsx-runtime] }flat config 对应版本为 configs/jsx-runtime.js。该预设还额外将parserOptions.jsxPragma置为null以适配typescript-eslint/parser的解析行为。自定义 pragmajsx注解与settings.react.pragma规则不仅检查React还会尊重文件级jsx注解以及 ESLint 共享设置中的settings.react.pragma。这一逻辑实现在 lib/util/pragma.js 的getFromContext中其优先级如下读取源码中所有注释用正则/jsx\s([^\s])/匹配第一个jsx注解lib/util/pragma.js若命中取注解值如Foo.bar中以.分隔的第一段即Foo作为 pragma若没有注解则回退读取context.settings.react.pragma若仍未配置默认返回React最后用JS_IDENTIFIER_REGEX/^[_$a-zA-Z][_$a-zA-Z0-9]*$/校验 pragma 是否为合法标识符不合法时打印警告并回退为React。也就是说jsx Foo.bar与jsx Foo在作用域检查层面等价——都只要求Foo变量存在。测试用例中/** jsx Foo.Bar */ var Foo, App; App /;被判定为 valid而/** jsx Foo.bar */ var React, a img /;被判定为 invalid报错变量名为Foo正是对这一规则的直接验证见 tests/lib/rules/react-in-jsx-scope.js 与 #L135-L143。若项目所有文件统一使用自定义 pragma也可以在.eslintrc的settings中配置{ settings: { react: { pragma: Foo, version: 18 } } }此时规则会改为检查Foo。测试中var Foo, App; App /;配上该settings即为 valid见 tests/lib/rules/react-in-jsx-scope.js。源码实现作用域查找与版本感知监听节点与检查流程规则主体在 lib/rules/react-in-jsx-scope.js逻辑非常精简create返回对两类 AST 节点的监听——JSXOpeningElement如App与JSXOpeningFragment如并对每个节点调用checkIfReactIsInScope。这意味着普通的 JSX 元素、自闭合标签以及 Fragment 简写形式都会被检查测试中的var a fragment/;invalid 用例印证了 Fragment 也在检查范围内。作用域链回溯变量是否在作用域中由 lib/util/variable.js 的getVariableFromContext判定它从当前节点的 scope 出发先查找scope.variables再逐层向上scope scope.upper回溯直到找到同名变量或耗尽整条作用域链。因此嵌套函数、块级作用域内使用 JSX 时只要外层如模块顶层声明了React同样能通过检查。React 19自动禁用从源码中可以看出一条重要特性create函数开头会调用testReactVersion(context, 19.0.0)若当前项目检测到 React 版本不低于 19.0.0则直接返回空对象{}即该规则被自动禁用lib/rules/react-in-jsx-scope.js。原因在于 React 19 强制启用自动 JSX transformReact不再需要也不允许依赖在作用域中。测试用例中settings: { react: { version: 19.0.0 } }下的多段代码包括完全没有声明React的情况均被判定为 valid见 tests/lib/rules/react-in-jsx-scope.js。版本比较基于 lib/util/version.js 的getReactVersionFromContext它优先读取settings.react.version支持detect值通过resolve.sync(react)定位并读取已安装的 react 包版本也支持从settings.react.defaultVersion读取兜底版本未指定时使用999.999.999作为最新版本默认值。因此即使你使用recommended预设只要settings.react.version配置为19或detect且检测到 React 19本规则也会静默失效。何时不使用该规则根据 docs/rules/react-in-jsx-scope.md 的说明以下两类场景不应启用此规则项目不使用 JSX没有 JSX 就没有React.createElement展开检查毫无意义将React设为全局变量例如在浏览器环境通过script直接引入全局React或通过 ESLint 的globals声明React: true此时无需在模块内声明即可通过作用域检查。此外使用 React 17 新 JSX transform 的项目应通过扩展plugin:react/jsx-runtime关闭本规则同时关闭react/jsx-uses-react以消除导入未使用的误报与冗余导入而在 React 19 项目中如前文所述规则会被版本检测机制自动禁用无需手动配置。小结与最佳实践react-in-jsx-scope是一条编译模型驱动的静态检查规则它的存在意义来自旧版 JSX 的React.createElement展开机制。实际项目中的落地建议如下旧版 JSX Babel 传统 transform沿用plugin:react/recommended预设让规则以 error 级别拦截所有未引入React的 JSX 文件自定义 pragma如 Preact 的h、/** jsx h */通过settings.react.pragma或文件级注解定制规则会自动切换到对应变量React 17 新 JSX transform切换为plugin:react/jsx-runtime预设与react/jsx-uses-react一并关闭React 19 项目无需任何配置版本检测会自动禁用本规则全局React场景在globals中声明React后关闭规则避免误报。如需深入阅读实现细节可依次查阅规则源码 lib/rules/react-in-jsx-scope.js、pragm 解析工具 lib/util/pragma.js、作用域查找工具 lib/util/variable.js、版本检测工具 lib/util/version.js以及覆盖全部合法/非法场景的测试套件 tests/lib/rules/react-in-jsx-scope.js。赞分享开发工具代码质量静态分析【免费下载链接】eslint-plugin-reactReact-specific linting rules for ESLint项目地址https://gitcode.com/gh_mirrors/es/eslint-plugin-react点击查看免费下载相关推荐ESLint React最佳实践JSX语法检查与React规则配置ESLint React最佳实践JSX语法检查与React规则配置 引言为什么React项目需要专门的ESLint配置 在现代前端开发中React已经成开发工具Lint静态分析代码质量ESLint-Plugin-React的JSX规则终极指南语法检查与代码风格优化ESLint Plugin React的JSX规则终极指南语法检查与代码风格优化 ESLint Plugin React是专为React项目打造的ESLint开发工具代码质量静态分析深入解析eslint-plugin-react中的jsx-curly-spacing规则深入解析eslint plugin react中的jsx curly spacing规则 什么是jsx curly spacing规则 jsx curly sp开发工具代码质量静态分析上一篇Vant 组件库 useRelation 使用指南基于 provide/inject 的父子组件通信方案下一篇Relay 20 刷新查询Refreshing Queries实战指南useQueryLoader、useLazyLoadQuery 与 fetchQuery 三种刷新方案详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考