Next.js模块联邦部署报错：TypeError: g.useSyncExternalStore is not a function

DevOps 小满

2026-6-29

解决Next.js + Module Federation下useSyncExternalStore报错问题

升级@tanstack/react-query到v5后，你的应用独立运行正常，但在Module Federation模式下出现TypeError: g.useSyncExternalStore is not a function，本质原因是React 18内置的useSyncExternalStore Hook在联邦模块共享机制中没有被正确传递，导致远程模块无法找到这个方法。以下是几个可行的解决方案：

方案一：正确配置React和ReactDOM的共享模块

在你的next.config.js的Module Federation配置里，把react和react-dom设置为单例共享模块，确保整个联邦应用中只有一个React实例：

const { withModuleFederation } = require('@module-federation/nextjs-mf');

module.exports = withModuleFederation({
  // 你的其他联邦配置（比如name、filename、remotes等）
  shared: {
    react: {
      singleton: true,
      requiredVersion: '^18.2.0',
    },
    'react-dom': {
      singleton: true,
      requiredVersion: '^18.2.0',
    },
    // 若项目用到react-dom/client也建议加入共享
    'react-dom/client': {
      singleton: true,
      requiredVersion: '^18.2.0',
    },
  },
});

方案二：共享@tanstack/react-query模块

将@tanstack/react-query也加入共享配置，保证主应用和所有远程应用使用同一版本的库，避免版本差异导致的Hook调用问题：

// 在shared配置中添加
'@tanstack/react-query': {
  singleton: true,
  requiredVersion: '^5.22.2',
},

方案三：临时全局挂载React（应急方案）

如果上述共享配置不生效，可以在主应用的_app.jsx/_app.tsx入口文件中，手动将React挂载到全局对象，让远程模块能直接访问内置Hook：

import React from 'react';

if (typeof window !== 'undefined') {
  window.React = React;
}

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}