NextJS中Webpack Module Federation的React版本兼容问题

核心问题分析 #

• 硬设version:"0"：NextJS宿主中能共享单例React，但独立运行时webpack会尝试寻找共享作用域中版本为0的React，找不到就加载无效模块，触发createContext is not a function错误。
• 移除version：宿主中可能出现多React实例，违反Hook规则，导致无效Hook调用错误。

兼容配置方案 #

通过动态配置shared选项，让微应用在宿主环境复用单例React，独立运行时 fallback 到本地依赖：

Webpack配置示例 #

const packageJson = require('./package.json');

module.exports = {
  // ...其他webpack配置
  plugins: [
    new ModuleFederationPlugin({
      name: 'reactMicroApp',
      filename: 'remoteEntry.js',
      exposes: {
        './App': './src/App',
      },
      // 根据环境变量判断是否启用远程依赖（嵌入模式）
      remotes: process.env.REACT_APP_EMBEDDED === 'true' ? {
        nextHost: 'nextHost@http://localhost:3000/_next/static/chunks/remoteEntry.js'
      } : {},
      shared: {
        react: {
          singleton: true, // 强制单例，避免多实例Hook错误
          version: packageJson.dependencies.react, // 使用本地package.json的React版本
          requiredVersion: false, // 允许共享作用域无匹配版本时，fallback到本地依赖
          eager: true, // 同步加载，适配NextJS SSR场景
        },
        'react-dom': {
          singleton: true,
          version: packageJson.dependencies['react-dom'],
          requiredVersion: false,
          eager: true,
        },
      },
    }),
  ],
};

NextJS宿主侧配置配合 #

宿主的ModuleFederationPlugin需同步配置react和react-dom为单例，确保微应用复用宿主实例：

// NextJS的webpack配置（next.config.js）
const packageJson = require('./package.json');

module.exports = {
  webpack(config) {
    config.plugins.push(
      new ModuleFederationPlugin({
        name: 'nextHost',
        filename: 'remoteEntry.js',
        exposes: {},
        shared: {
          react: {
            singleton: true,
            version: packageJson.dependencies.react,
            requiredVersion: false,
            eager: true,
          },
          'react-dom': {
            singleton: true,
            version: packageJson.dependencies['react-dom'],
            requiredVersion: false,
            eager: true,
          },
        },
      })
    );
    return config;
  },
};

环境变量控制 #

• 嵌入模式：启动微应用时设置REACT_APP_EMBEDDED=true，让webpack加载宿主的远程依赖并共享React。
• 独立运行：不设置该变量，webpack不加载远程依赖，直接使用本地React实例。

关键配置说明 #

• singleton: true：强制整个应用中只有一个React实例，彻底解决无效Hook调用问题。
• requiredVersion: false：当共享作用域中没有匹配版本的React时，自动使用本地依赖，避免独立运行时的模块加载错误。
• eager: true：确保React同步加载，适配NextJS的SSR渲染逻辑，避免异步加载导致的实例不一致。

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