升级React17启用新JSX转换后运行报错该如何解决？

核心原因 #

最常见的触发原因是项目中存在多个React副本实例，开启runtime: 'automatic'后暴露了这个隐性问题：

• 旧的JSX转换逻辑是将JSX编译为React.createElement调用，所有代码都依赖你手动引入的同一个React实例
• 新的自动转换会自动在每个JSX文件头部注入import { jsx } from 'react/jsx-runtime'，如果依赖树中存在多个版本的React，或者部分React引入没有走统一的依赖解析，就会出现多个互不关联的React实例，直接触发Hook调用规则校验失败，同时伴随各类状态更新异常警告

其他可能的诱因：

• React和ReactDOM版本不匹配，未同步升级到17.0.0及以上版本
• webpack的externals配置未适配新的JSX runtime，导致全局引入的React和自动打包的react/jsx-runtime属于不同实例
• babel配置作用范围不正确，部分JSX文件未应用automatic runtime配置
• 旧版本第三方依赖（如你用到的React-Table）未兼容React17+的JSX转换规则

解决方案 #

按优先级依次排查处理：

1. 校验并固定React版本
   执行命令检查依赖树中的React版本：

   # npm用户
   npm ls react
   npm ls react-dom
   # yarn用户
   yarn list react
   yarn list react-dom
   

   如果出现多个版本的React/ReactDOM，在package.json中添加配置固定版本：

   // npm 8+ 新增到package.json根节点
   "overrides": {
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   }
   // yarn 用户新增到package.json根节点
   "resolutions": {
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   }
   

   配置完成后删除node_modules和锁文件，重新执行依赖安装。

2. 适配webpack externals配置（如果有用到全局引入React）
   如果你之前通过CDN引入React，配置了externals跳过React打包，需要新增react/jsx-runtime的 externals 规则：

   // webpack.config.js
   module.exports = {
     externals: {
       'react': 'React',
       'react-dom': 'ReactDOM',
       // 新增这一行，适配自动转换的引入
       'react/jsx-runtime': 'React'
     }
   }
   

3. 确认babel配置覆盖范围
   检查babel-loader的test规则是否匹配所有.jsx/.tsx后缀的文件，exclude规则不要误伤需要处理的业务代码，同时删除单独配置的@babel/plugin-transform-react-jsx插件，避免和@babel/preset-react的配置冲突。

4. 升级第三方依赖
   将React-Table升级到支持React17的最新版本，避免旧版本依赖的内部兼容问题。

内容的提问来源于stack exchange，提问作者HaveSpacesuit