Next.js Module Federation插件下HMR热更新失效问题排查

核心问题分析 #

当前问题根源在于服务器端remoteEntry缓存未更新、模块联邦未适配Next.js SSR的双构建模式，再加上NX的缓存机制放大了旧代码残留的问题，导致修改组件后服务器仍加载旧版本，引发HMR失效和水合不匹配。

解决方案步骤 #

1. 修复Checkout应用的Webpack配置（适配SSR双构建）

Checkout应用未区分客户端/服务器端构建，导致SSR环境下remoteEntry路径错误、旧代码缓存。修改配置如下：

// for the checkout app
webpack: (config, { isServer, dev }) => {
  // 区分客户端/服务器端的remoteEntry路径
  const filename = isServer 
    ? 'static/ssr/remoteEntry.js' 
    : 'static/chunks/remoteEntry.js';
  
  config.plugins.push(
    new NextFederationPlugin({
      name: 'checkout',
      filename: filename,
      exposes: {
        './checkout': './pages/checkout.tsx',
      },
      // 共享React核心依赖，避免多实例引发水合错误，同时支持HMR
      shared: {
        react: { singleton: true, eager: true, requiredVersion: false },
        'react-dom': { singleton: true, eager: true, requiredVersion: false },
      },
      extraOptions: {
        enableImageLoaderFix: true,
        enableUrlLoaderFix: true,
        exposePages: true,
        automaticAsyncBoundary: true, // 自动处理远程组件的SSR水合边界
      },
    })
  );

  // 开发模式下禁用Webpack缓存，确保修改立即生效
  if (dev) {
    config.cache = false;
  }

  return config;
},

2. 优化Main应用的Webpack配置（避免remoteEntry缓存）

Main应用需要在开发模式下规避remoteEntry的缓存，同时同步核心依赖的共享配置：

// for the main app
webpack: (config, { isServer, dev }) => {
  const location = isServer
    ? '_next/static/ssr/remoteEntry.js'
    : '_next/static/chunks/remoteEntry.js';
  
  // 开发模式下给remote URL加时间戳，彻底避免浏览器/服务器缓存旧remoteEntry
  const remoteUrl = dev 
    ? `http://localhost:3001/${location}?t=${Date.now()}` 
    : `http://localhost:3001/${location}`;

  config.plugins.push(
    new NextFederationPlugin({
      name: 'main',
      filename: 'static/chunks/remoteEntry.js',
      exposes: {},
      remotes: {
          checkout: `checkout@${remoteUrl}`
      },
      shared: {
        react: { singleton: true, eager: true, requiredVersion: false },
        'react-dom': { singleton: true, eager: true, requiredVersion: false },
      },
      extraOptions: {
        enableImageLoaderFix: true,
        enableUrlLoaderFix: true,
        automaticAsyncBoundary: true,
      },
    })
  );

  // 开发模式下禁用服务器端Webpack缓存
  if (isServer && dev) {
    config.cache = false;
  }

  return config;
},

3. 调整NX开发缓存策略

NX的默认缓存会保留旧构建产物，需在两个应用的project.json中禁用开发模式缓存：

// 以checkout应用为例，修改project.json中的serve配置
"serve": {
  "executor": "@nrwl/next:server",
  "options": {
    "buildTarget": "checkout:build",
    "dev": true,
    "noCache": true // 禁用开发缓存
  }
}

4. 可选：临时规避水合错误（用于排查）

如果上述修改后仍有水合问题，可尝试用next/dynamic加载远程组件并临时关闭SSR：

// 在main应用中加载远程组件的地方
import dynamic from 'next/dynamic';

const CheckoutComponent = dynamic(() => import('checkout/checkout'), { 
  ssr: false,
  loading: () => <div>Loading...</div>
});

注：此方法仅用于排查，优先修复SSR缓存问题以保留服务端渲染能力。

验证方法 #

1. 重启两个应用的开发服务器
2. 修改Checkout应用的checkout.tsx组件内容
3. 等待Checkout服务器完成热更新后，切换到Main应用查看：
   • HMR应自动触发，页面无需刷新即可更新
   • 手动刷新页面无Hydration failed类错误

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