Module Federation：更新NextJS Remote致Host触发Hydration failed错误

问题背景 #

• 远程NextJS应用：本地5000端口启动（执行npm run dev），访问http://localhost:5000/user/12可正常渲染用户详情；修改文本内容后，远程应用自身能正常显示更新后的内容。
• 宿主NextJS应用：本地4000端口启动（执行npm run dev），原本访问http://localhost:4000/host-page-user/12可正常渲染远程应用提供的用户信息（无需在宿主中编写api/*相关逻辑）。

出现的问题 #

修改远程应用的文本内容后，宿主应用出现Hydration不匹配错误：

• 开发环境：控制台弹出警告 Warning: Text content did not match. Server: "Test" Client: "Testing"，同时报错 Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
• 生产环境：提示变为 Error: Text content does not match server-rendered HTML，控制台报错与开发环境一致。

排查与解决建议 #

1. 清除宿主应用缓存
   宿主应用可能缓存了远程模块的旧版本，导致服务端渲染用了旧文本，客户端加载了新文本，引发不匹配。

   • 操作：重启宿主应用的开发服务；删除宿主应用的.next目录后重新执行npm run dev；生产环境需确保远程应用更新后，宿主能拉取最新的远程模块（可在远程模块入口添加版本号，避免CDN或缓存机制保留旧内容）。

2. 检查模块联邦配置的一致性
   NextJS模块联邦在服务端和客户端的模块拉取逻辑可能存在差异，导致服务端无法获取最新的远程代码。

   • 操作：确认模块联邦配置中，远程模块的url在服务端和客户端都指向正确的最新地址；开发环境可尝试禁用模块缓存（通过配置cache: false）。

3. 验证远程组件的SSR兼容性
   虽然本次问题由文本修改引发，但仍需确保远程组件中没有依赖客户端环境的代码（如直接访问window），这类代码会导致服务端渲染内容与客户端不一致。

   • 操作：检查远程组件的渲染逻辑，确保服务端和客户端生成的内容完全一致；若存在客户端特有的逻辑，需用useEffect或dynamic import（禁用SSR）包裹。

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