自动JSX运行时是什么？为什么不用再importReact？

传统运行时与自动运行时的本质差异

要弄清楚为什么可以省略 import React，首先需要理解 JSX 到底是什么。浏览器本身无法直接执行类似 <div className="box">内容</div> 的 JSX 标记语言。在项目构建阶段，代码必须经过编译器转换成合法的 JavaScript 函数调用。两个运行时方案的根本分歧，正是转译后的目标函数及其解析方式。

传统运行时（Classic Runtime）：为什么过去必须导入 React？

在传统模式（Classic Runtime）下，编译器默认将每一个 JSX 节点一对一转译为 React.createElement。例如一段简单的组件代码：

// 源码阶段
import React from 'react';

function Header() {
  return <h1 id="title">标题文本</h1>;
}

经过 Babel 转译后，输出的代码如下：

// 编译输出阶段 (Classic Runtime)
import React from 'react';

function Header() {
  return React.createElement('h1', { id: 'title' }, '标题文本');
}

在上述转译产物中，函数执行体直接调用了名为 React 的标识符。如果在源码中没有编写 import React from 'react'，执行环境中就不存在 React 这一变量，代码在执行时就会立即抛出未定义异常。即使开发者只写了一行纯展示性质的 JSX，也必须引入整个庞大的 React 命名空间。

自动运行时（Automatic Runtime）：编译器如何接管引用？

React 团队联合 Babel 官方在 React 17 中推出了全新的 JSX 转换方案。在这个模式下，编译器在遇到 JSX 标签时，会自动识别并向生成文件头部注入专用的轻量方法，同时把 JSX 改写为内部函数调用：

// 开发者编写的源码（无需引入 React）
function Header() {
  return <h1 id="title">标题文本</h1>;
}

// 编译输出阶段 (Automatic Runtime 自动注入)
import { jsx as _jsx } from 'react/jsx-runtime';

function Header() {
  return _jsx('h1', {
    id: 'title',
    children: '标题文本'
  });
}

由于引用注入的过程完全由编译器在底层自动化完成，开发者在编写组件时，自然不需要再在顶部手动写下任何与 JSX 渲染相关的导入声明。

为什么不直接自动引入 React.createElement？

很多人初次接触该机制时会有疑问：如果仅仅是为了省去手动导入，为什么编译器不直接在文件头部自动插入 import React from 'react' 呢？

React 官方之所以设计全新的 react/jsx-runtime，核心目标是为了解决 React.createElement 遗留的历史包袱，并带来实质性的性能与打包收益：

1. 属性解析与 key 处理的开销优化

在过去的 React.createElement(type, config, ...children) 签名中，传入的 config 对象同时混合了普通属性和特殊属性（如 key 与 ref）。在运行时内部，React 必须对 config 执行动态遍历和浅拷贝，检查其中是否存在 key，将其抽离出来后再把剩余属性赋值给新的 props 对象。

在自动 JSX 运行时中，新的函数签名变更为 _jsx(type, props, key)。编译器在静态语法分析阶段就已经识别出哪个属性是 key，并直接将其作为独立的第三个参数传入。这样在运行时完全免去了动态检索和属性删除的开销，对象结构更为稳定，有利于 JavaScript 引擎的内联缓存优化。

2. 单子节点与静态多子节点分流（jsx vs jsxs）

编译器能够明确知道组件的子节点是单一元素还是固定的多个元素：

• 单一子元素：编译器调用 _jsx，并将子元素直接作为 props.children 单个对象传递，避免了传统模式下通过剩余参数语法（Rest Parameters）创建临时数组的内存分配。
• 静态多个子元素：编译器调用专用函数 _jsxs。这明确告知 React 内部：这些子元素的顺序在编译期就已经确定，运行时无需再做动态数组的层层类型检查与警告判断。

3. 解绑顶层对象与打包体积（Tree Shaking）

传统模式强行将 JSX 与全局的 React 命名空间捆绑。即使一个页面或微组件只需要简单渲染标签，打包器也常常被迫打包进 React 命名空间上的大量属性与方法。通过将运行时剥离至独立的子路径 react/jsx-runtime，打包器能够更好地执行摇树优化（Tree Shaking），剔除不需要的代码。

主流工具链配置与迁移步骤

在目前绝大多数通过现代脚手架（如 Vite、Next.js 12+、Create React App 4+）创建的项目中，自动 JSX 运行时已经作为默认配置启用。但如果是在老旧项目升级、自建 Webpack 流程或定制 TypeScript 配置时，需要按照以下四个步骤进行确认与配置。

第 1 步：确认 React 核心库版本

自动运行时要求 React 核心包中必须包含 react/jsx-runtime 入口。检查项目 package.json，确保满足以下版本前提：

• React >= 17.0.0（React 18、19 原生支持）
• 若维护旧版本项目，官方已向后兼容回发了 16.14.0 与 15.7.0 补丁版本。

第 2 步：调整编译器配置（TypeScript 与 Babel）

根据项目采用的编译工具，将 JSX 转译目标由传统模式切换为自动模式：

如果项目使用 TypeScript：打开 tsconfig.json，将 compilerOptions.jsx 设置为 react-jsx（针对生产）或保留在支持自动转换的选项：

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "moduleResolution": "node",
    // 关键配置：从 "react" 改为 "react-jsx"
    "jsx": "react-jsx"
  }
}

如果项目使用 Babel：在 babel.config.js 或 .babelrc 中，为 @babel/preset-react 增加 runtime: 'automatic'：

// babel.config.js
module.exports = {
  presets: [
    [
      '@babel/preset-react',
      {
        runtime: 'automatic' // 默认为 'classic'，此处显式指定为 'automatic'
      }
    ]
  ]
};

第 3 步：更新代码检查（ESLint）规则

在很多旧项目中，开启了 eslint-plugin-react 的检查规则。当删除组件顶部的 import React 后，ESLint 会抛出错误：'React' must be in scope when using JSX (react/react-in-jsx-scope)。

为了解决这个误报，需要在 ESLint 配置文件中关闭这两条旧规则：

// .eslintrc.json
{
  "rules": {
    // 自动运行时不再需要局部作用域存在 React 变量
    "react/react-in-jsx-scope": "off",
    // 避免导入的 React 被误标记为未使用变量
    "react/jsx-uses-react": "off"
  }
}

第 4 步：使用官方脚本批量清理冗余导入

完成上述配置后，项目中已有的 import React from 'react' 不会导致构建失败，但它已经变成了无用的样板代码。React 官方提供了自动化重构工具，可以一次性扫描项目并安全移除不必要的导入：

# 在项目根目录下执行迁移脚本
npx react-codemod update-react-imports

该命令会智能分析代码：如果文件仅仅使用了 JSX，它会自动删除 import React from 'react'；如果文件中还用到了 React.useState，它会自动改写为解构导入 import { useState } from 'react'。

什么时候依然需要 import 语句？

“不用再 import React”特指不再需要为了让 JSX 正常工作而引入 React 全局变量。在组件需要使用 React 提供的其他功能时，依然需要引入具体的 API 或类型。

总结

自动 JSX 运行时本质上是编译期代码转换策略的一次重要进化。它将原本强行绑定在开发者手指下的冗余导入工作交还给编译器处理，通过引入独立的 react/jsx-runtime 入口，不仅消除了千百个组件文件中千篇一律的 import React from 'react'，还优化了底层虚拟 DOM 节点的生成路径与内存开销。

理解自动运行时的工作方式，有助于我们在排查诸如 ESLint 误报、TypeScript 类型解析失败或打包体积异常等工程化问题时，迅速定位根源并做出准确配置。