Module Federation React TS应用远程组件报useState空引用错误

DevOps 小满

2026-8-30

问题说明

核心报错：

Uncaught TypeError: Cannot read properties of null (reading 'useState')

场景基础信息：

技术栈：React + TypeScript，采用Module Federation（模块联邦）架构，包含host宿主应用、remote远程应用两个独立部署单元
已知正常表现：宿主应用引入远程端导出的普通Button组件时运行无异常，可正常读取props键值、读取默认props完成渲染
已知异常表现：宿主应用引入远程端基于recharts封装的自定义BarChart组件时，控制台直接打印props可看到完整传入数据，但组件内部无法读取props值，最终触发上述报错；BarChart组件定义中所有传入属性均标记为可选属性

根因判断

该报错在模块联邦场景下的核心诱因是React多实例冲突：
普通Button组件未使用React Hooks，也没有依赖带Hooks调用的第三方逻辑，所以即使存在多实例也不会触发报错；而封装的BarChart组件依赖的recharts内部会大量调用useState、useEffect等React Hooks，当host和remote各自打包了独立的React实例时，Hooks调用会从当前执行上下文的React对象中读取dispatcher调度器，跨实例调用时会拿到值为null的dispatcher，直接触发类型错误。
控制台能打印props但组件内部读不到，也是多实例冲突的典型表现：日志打印是在JS通用作用域链中取值，能拿到传入的参数，但React内部的渲染上下文、props传递链路因为多实例被切断，组件实例挂载时拿不到对应的props和状态上下文。

排查步骤

确认是否存在多React实例
在host、remote两个应用的入口文件中加入以下打印代码：
```
import * as React from 'react'
console.log('当前应用React实例引用：', React)
console.log('当前页面React渲染器数量：', window.__REACT_DEVTOOLS_GLOBAL_HOOK__?.renderers?.size)
```
页面加载后如果控制台打印出两个引用地址不同的React对象，或者React渲染器数量大于1，即可确认是多实例问题。
核对两端模块联邦配置，检查React、React-DOM是否配置了单例共享规则，确认第三方依赖recharts是否存在重复打包的情况。
检查打包缓存：修改配置后如果问题复现，先清除构建缓存（webpack缓存、.vite缓存、dist目录）再重启服务，避免旧缓存导致配置不生效。

可行解决方案

按落地优先级从高到低排序：

方案1：统一配置单例共享依赖（适配绝大多数场景）
同步修改host、remote两端的模块联邦配置（webpack对应ModuleFederationPlugin配置，vite对应vite-plugin-federation配置），将React相关核心依赖声明为单例共享：

// 两端shared配置保持一致
shared: {
  react: {
    singleton: true,
    requiredVersion: require('./package.json').dependencies.react,
    eager: true // 宿主端建议开启eager，规避共享依赖异步加载的时序问题
  },
  'react-dom': {
    singleton: true,
    requiredVersion: require('./package.json').dependencies['react-dom'],
    eager: true
  },
  recharts: {
    singleton: true,
    requiredVersion: require('./package.json').dependencies.recharts
  }
}

注意：两端React、React-DOM、recharts的大版本需要保持一致，否则共享逻辑会 fallback 到本地打包的依赖，依然会出现多实例。

方案2：外置React依赖彻底规避重复打包
如果共享配置始终不生效，可以在两端打包配置中将React、React-DOM设置为外部依赖，不打入业务chunk，统一在HTML模板中引入同版本的React、ReactDOM全局资源：
```
// webpack.config.js 配置示例
externals: {
  react: 'React',
  'react-dom': 'ReactDOM'
}
```
方案3：版本对齐兜底
如果存在历史项目版本限制，先将host、remote两端的React、React-DOM版本对齐到完全相同的版本号，删除lock文件、node_modules后重新安装依赖再构建，避免因版本差异导致共享依赖加载失败。

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