Vite 模块联邦踩坑实录：带你闭坑

第一个坑：remoteEntry.js 404，人都傻了

崩溃现场

我按照官方文档配置好了远程应用（表单设计器），信心满满地 npm run dev，然后在主应用里引入远程组件。结果浏览器控制台直接给我来了一个：

GET http://localhost:3001/mf/remoteEntry.js 404 (Not Found)

我一脸懵逼：配置明明写了 filename: 'mf/remoteEntry.js'，为啥找不到？

闭坑方案

后来我才发现，@originjs/vite-plugin-federation 这个插件有个大坑：

也就是说，远程应用必须用 构建模式 才能生成 remoteEntry.js。我改了 package.json：

{
  "scripts": {
    "dev": "vite",
    "dev:mf": "vite build --watch",
    "dev:remote": "npm run dev:mf & npm run preview",
    "preview": "vite preview --port 3001"
  }
}

然后运行 npm run dev:remote，终于看到 build/assets/mf/remoteEntry.js 生成了！

第二个坑：Top-level await 报错，又懵了

崩溃现场

好不容易解决了 404，结果浏览器又给我来了一个：

Top-level await is not available in the configured target environment

我心想：啥玩意儿？我又没写 await，哪来的 top-level await？

闭坑方案

后来我翻了半天源码才发现，模块联邦生成的代码里用了 top-level await，而 Vite 默认的 target 是 es2020，不支持这个特性。

我改了 vite.config.js：

export default defineConfig({
  esbuild: {
    target: 'esnext',
  },
  optimizeDeps: {
    esbuildOptions: {
      target: 'esnext',
    },
  },
  build: {
    target: 'esnext',
  },
});

重新构建，终于不报错了！

第三个坑：Failed to resolve module specifier，崩溃三连

崩溃现场

前两个坑填完了，我以为终于可以跑起来了。结果浏览器又给我来了一个：

Failed to resolve module specifier "form_designer_remote"

我一看主应用的配置：

remotes: {
  formDesigner: 'form_designer_remote@http://localhost:3001/assets/mf/remoteEntry.js'
}

这不是官方文档的写法吗？为啥不行？

闭坑方案

后来我发现，@originjs/vite-plugin-federation 的配置格式和 Webpack 的不一样！

remotes: {
  formDesigner: {
    external: 'http://localhost:3001/assets/mf/remoteEntry.js'
  }
}

改完之后，终于跑起来了！泪目！

闭坑方案：完整可用的配置

远程应用配置（表单设计器）

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from '@originjs/vite-plugin-federation';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'form_designer_remote',
      filename: 'mf/remoteEntry.js',
      exposes: {
        './FormDesigner': './src/views/FormDesigner/FormDesigner.jsx',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  esbuild: {
    target: 'esnext',
  },
  optimizeDeps: {
    esbuildOptions: {
      target: 'esnext',
    },
  },
  build: {
    target: 'esnext',
    minify: false,
    cssCodeSplit: false,
  },
});

主应用配置（流程引擎）

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from '@originjs/vite-plugin-federation';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'process_engine_host',
      remotes: {
        formDesigner: {
          external: 'http://localhost:3001/assets/mf/remoteEntry.js'
        }
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.2.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
      },
    }),
  ],
  server: {
    port: 3900,
    cors: true,
  },
});

使用远程组件

// RemoteFormDesigner.tsx
import { lazy, Suspense } from 'react';
import { Spin } from 'antd';

const FormDesigner = lazy(() => import('formDesigner/FormDesigner'));

function RemoteFormDesigner(props) {
  return (
    <Suspense fallback={<Spin size="large" tip="加载表单设计器..." />}>
      <FormDesigner {...props} />
    </Suspense>
  );
}

export default RemoteFormDesigner;

开发流程：一键启动

# 1. 远程应用：一键启动构建+预览
cd lowcodeform-frontend
npm run dev:remote

# 2. 主应用：启动开发服务器
cd ProcessEngineServer/client
npm run dev

访问主应用：http://localhost:3900，终于看到远程组件加载成功了！

开发联调架构流程

问题排查流程：遇到问题怎么办？

如果你也遇到了模块联邦的问题，可以按照这个流程图快速定位：

总结：三个关键点

希望这篇文章能帮你少踩点坑。如果你还遇到其他问题，欢迎加作者交流！

终极方案：一劳永逸解决所有问题

说实话，上面这些坑踩下来，我已经对 @originjs/vite-plugin-federation 失去信任了。它的问题不是一个两个，而是设计层面的缺陷：

• 开发模式不能用，必须 build --watch，体验割裂
• target 要配三遍，封装不到位
• 配置格式和 Webpack 不兼容，迁移成本高
• 热更新不生效，改代码要手动刷新
• 共享依赖版本冲突时报错信息不友好
• 微前端场景下 CSS 样式冲突，主应用和子应用样式互相污染

如果你也受够了这些问题，可以试试我封装的插件组合（持续更新）：

安装使用：

# 安装模块联邦核心插件
npm install @jiayouzuo/vite-module-federation-core

# 如果需要样式隔离，额外安装
npm install @jiayouzuo/vite-plugin-css-scope

配置示例（远程应用）：

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from '@jiayouzuo/vite-module-federation-core';
import cssScope from '@jiayouzuo/vite-plugin-css-scope';

export default defineConfig({
  plugins: [
    // 可选：CSS 作用域隔离，需要再react之前进行
    cssScope({
      scope: 'remote-app',
      include: ['src/'],
    }),
    react(),
    federation({
      name: 'remote_app',
      filename: 'remoteEntry.js',
      exposes: {
        './FormDesigner': './src/views/FormDesigner/FormDesigner.jsx',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
});

配置示例（主应用）：

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from '@jiayouzuo/vite-module-federation-core';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'host_app',
      remotes: {
        remoteApp: {
          external: 'http://localhost:3001/assets/remoteEntry.js',
          from: 'vite',
          format: 'esm',
        },
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
});

就这么简单，不用配 target，不用 build --watch，直接 npm run dev 就能用。样式冲突？加上 css-scope 插件一键解决。

相关技术文献资源

如果你想深入了解 Vite 模块联邦的更多细节，可以参考以下资源：

• vite-plugin-federation GitHub 仓库 - 官方源码和 Issues
• vite-plugin-federation - 官方文档 - 完整的配置指南和 API 说明
• module-federation - 官方文档 - 完整的配置指南和 API 说明
• Issue #410 - remoteEntry.js 404 问题讨论