微前端架构落地：Module Federation + Monorepo + 低代码平台实践

去年 Q3，我们内部平台的前端代码量到了一个临界点。单仓库单应用，70 多个路由页面，超过 10 万行业务代码，一次发版全量构建要 8 分钟，改一行公共组件也要走完整发布流程。团队三个小组挤在一个仓库里，merge 冲突频繁到已经影响日常迭代。摆在桌面上的方案有两类：一类是 qiankun 这种运行时沙箱微前端，一类是 Webpack Module Federation 这种模块级共享方案。最后我们选了 Module Federation，顺手把仓库改造成 pnpm Monorepo，再往上搭了一套物料化低代码平台。

这篇文章不是官方文档的复述，是项目落地之后回头写的一份复盘。重点讲选型时没写在文档里的权衡、大仓边界怎么切、物料注册机制怎么设计、运行时动态加载链路，还有几个让我排查到凌晨的坑。适合准备做微前端拆分、准备搭低代码平台，或者正在纠结要不要上 Monorepo 的团队参考。

先说结论：这套架构最后跑通了。主应用承载壳和基础布局，三个业务子应用独立开发独立部署，物料库让运营能拖拽生成配置页，整体构建时间从 8 分钟降到 1 分半。

1. 从单体巨石到微前端：一次选型复盘

1.1 当时的痛点：一次发布要牵动所有页面

单体应用的痛点，网上已经写烂了，但真正踩过才知道那根刺扎在什么地方。我们当时的问题不是构建慢这么简单，而是三个小组的业务逻辑高度耦合在一个代码库里。运营后台的代码会依赖数据看板的公共组件，数据看板又反过来引入运营后台的工具函数，时间一长，谁也不敢动公共层，因为一改就是十几处连锁改动。

更尴尬的是，我们想引入 Vue 3 做一部分新页面。单体 React 应用内部插 Vue 不是不行，但要同时维护两套构建配置、两套路由、两套状态管理，单页应用的路由切换还容易互相踩全局事件。这个诉求直接推着我们往微前端方向走——不是纯拆业务，而是要把"不同技术栈的区域"从物理上隔开。

当时梳理下来的核心诉求有三个：

• 业务子应用能独立开发、独立部署，发布某个模块不能牵连全局。
• 公共依赖（React、React Router、axios）在运行时尽量只加载一份，不要每个子应用都带着一个 React 上街。
• 新老技术栈可以共存，后续新模块可以用 Vue 3 或更激进的框架，不需要先做技术债迁移。

1.2 为什么放弃 qiankun 而选了 Module Federation

这个选择网上争论很多。qiankun 的沙箱机制成熟，JS 沙箱、样式隔离、loadApp 生命周期管理都做得比较完整，接入时对子应用的构建工具也不挑剔。但我们实测后发现，qiankun 的接入模型对这个场景太重了。

qiankun 要求子应用必须暴露 bootstrap/mount/unmount 生命周期，主应用通过 import-html-entry 机制把子应用的 HTML 拉下来解析执行。这个链路本身没问题，问题是我们要拆的不只是"应用"，还有"物料"。物料化低代码平台的核心是：一个远程组件，通过一段配置就能被运行时动态加载并渲染。qiankun 的模式是"注册一个应用"，而我们需要的是"注册一堆可组合的模块"，这两种粒度对不上。

Module Federation 的模型正好反过来了。它把远程模块当成一个普通的 webpack chunk，通过 exposes/remotes 声明谁提供什么、谁消费什么。远程组件和本地组件在打包时走同一套依赖图，TypeScript 类型、HMR、tree-shaking 全部贯通。低代码平台里的每一个物料，本质上就是一个远程模块，用 MF 来描述物料注册关系，不需要额外造一套加载协议。

下面这个表是我们当时做选型对比留下的记录：

当然 qiankun 也有 MF 比不上的地方。qiankun 的沙箱能拦截 document 访问和全局变量写入，MF 做不到这种级别的安全隔离。所以如果你们有硬性的第三方代码隔离要求，qiankun 仍然值得考虑。我们这里没有这种诉求，所有子应用都是自家团队维护，信任边界足够，MF 的"轻隔离 + 强共享"反而更实用。

1.3 技术验证阶段做过的三个最小 Demo

选型不能光靠脑补。我花了一个周末做了三个最小 Demo，基本摸清了 MF 的能力边界。

第一个 Demo 是 host 加载 remote 组件。主应用用 React 18，子应用也暴露一个 React 组件，通过 shared.react 配置验证两个应用是否只加载一份 React。这个 Demo 跑通后，我就放心了大半，因为公共依赖共享是 MF 最核心的价值。

第二个 Demo 是跨框架加载。我把一个 Vue 3 组件暴露成远程模块，主应用里用 React 的 React.createElement 包一层去渲染它。Vue 3 和 React 18 的实例互不干扰，但需要手动做生命周期对接。这个 Demo 直接决定了后续数据看板子应用可以用 Vue 3 开发。

第三个 Demo 和低代码平台相关。我把一个表单组件从应用里拆出来，做成远程物料，再通过一段 JSON schema 动态加载渲染。这个链路跑通之后，物料化的技术路线就确定了：物料 = MF 的 exposed 模块 + schema 描述。

这三个 Demo 花了大概一天半，换来的是整个架构方向的确定性。我一直觉得，微前端这种涉及全团队协作模式的技术改造，前期多花时间做验证 Demo，比后期在错误方向上修补要划算得多。

2. Monorepo 大仓：子应用边界如何切才不后悔

2.1 apps 与 packages 的划分逻辑

微前端解决了部署和运行时隔离的问题，但如果代码还堆在一个巨型仓库里，团队协作的摩擦并不会自动消失。所以我们在上 MF 的同时，把仓库改造成了 pnpm Monorepo。这一步当时有争议，有同事觉得"微前端 + Monorepo"是双重复杂度，可能得不偿失。现在回头看，两个一起上反而是对的——MF 负责运行时解耦，Monorepo 负责源码层共享，它们解决的问题正好互补。

大仓目录结构是这样的：

text复制apps/
  main-app/          # 主应用，MF host
  admin-app/         # 运营后台子应用，MF remote
  dashboard-app/     # 数据看板子应用（Vue 3），MF remote
  builder-app/       # 页面搭建器子应用，MF remote
packages/
  shared/            # 共享 tsconfig、ESLint 配置、通用工具函数
  design-system/     # 基础组件库
  material-schema/   # 物料描述类型与校验规则
  material-registry/ # 物料注册表，维护物料元信息
  http-client/       # 统一请求封装
  runtime-store/     # 跨应用共享的全局状态包

边界划分就一条铁律：会不会作为独立入口部署？ 会，就放 apps/；只是被其他应用引用，就放 packages/。builder-app 虽然本质是低代码平台的一部分，但它有独立的部署入口和独立的路由，所以它必须是一个子应用。material-registry 没有任何独立入口，它只是被主应用和 builder 应用消费的一个数据源，所以它是包。

这条规则看起来简单，实际讨论时很容易跑偏。有人建议把 design-system 直接放 apps/ 下面，因为"组件库以后也要独立发版"。这是把"独立发版"和"独立部署"混为一谈了。design-system 就算用 changesets 独立发版，它跑的仍然是发布流水线，不是部署流水线，没有服务器会为它单独启动一个服务。这个区别会直接影响依赖图的方向，必须在初期就定清楚。

2.2 pnpm workspace 依赖提升遇到的现实问题

Monorepo 里最容易翻车的不是目录结构，而是依赖管理。pnpm 默认的 node_modules 结构是符号链接 + 内容寻址存储，每个包只能访问自己声明的依赖，这个隔离机制对 MF 是双刃剑。

MF 的 shared 机制之所以能让多个应用共用一份 React，前提是 webpack 在解析依赖时能看到所有应用用的是同一个 React 实例。但 pnpm 的隔离模式下，如果 admin-app 和 main-app 各自在自己的 node_modules 里安装了不同 minor 版本的 React（哪怕只是 18.2.0 和 18.3.1 的差异），webpack 就会把它们当作两个模块分别打进产物，shared 配置直接失效。现象就是明明配了 shared: { react: { singleton: true } }，浏览器里还是加载了两份 React，Hooks 各种告警。

我们的解决办法是用 pnpm 的 catalog 功能锁定版本。在 pnpm-workspace.yaml 里定义：

yaml复制packages:
  - 'apps/*'
  - 'packages/*'

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
  react-router-dom: ^6.22.0
  typescript: ^5.4.0

然后在所有子应用和共享包的 package.json 里统一写 react: catalog:：

json复制{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:"
  }
}

这样 pnpm install 的时候，整个大仓的 React 都会被解析到同一版本。类似的关键依赖还有 @emotion/react、axios、lodash-es 这类库，建议全部进 catalog。

还有一个容易被忽略的点：如果某些包是通过 file: 协议从本地直接引用的，要确认它们在生产构建时不会产生第二份 React。我们当时 design-system 里的组件库用了 Emotion 的 css prop，如果 Emotion 不是单例，样式会出现随机丢失的问题。这个问题排查了很久，最后发现是 @emotion/react 在 design-system 和主应用里各装了一份，同样需要用 catalog 锁版本。

2.3 版本号策略：统一发版与独立发版的取舍

Monorepo 的版本策略，网上有两派：一类是 all-in-one 统一版本，所有包共用一个 version；另一类是 changesets 按包独立发布。我们一开始图省事选了统一版本，后来被物料场景教育了一顿。

问题出在物料库。material-registry 里的物料元信息会关联 design-system 组件的版本。如果统一发版，运营后台某个页面还在用旧物料，我就没法只升级 design-system 里的某个组件，必须把整个大仓的所有包一起发版，否则版本号就对不上。这在微前端场景下完全不可接受，因为每个子应用是独立部署的，线上可能存在三个不同版本的大仓代码在同时跑。

后来我们切换到 changesets 按包发布。apps/ 下的子应用不参与 changeset，它们走自己的 CI 部署；packages/ 下的共享包走 changeset 发布，每次 publish 会生成版本号，并自动更新依赖方的 package.json。这样升级链路变成了：修改 design-system → changeset 发版 → 需要新组件的子应用升级依赖 → 发版。整个过程是涟漪式的，而不是全量风暴。

3. 物料化低代码平台在大仓中的实现路径

3.1 物料的第一层抽象：schema 描述

低代码平台要落地，第一步不是写渲染器，而是定义清楚"物料是什么"。我们的答案是一份 JSON schema。界面里能拖拽的每一个组件，在代码层面都对应一条物料描述，包含组件标识、版本、类别、属性协议、事件协议和远程加载地址。

在 packages/material-schema 里，我们用 TypeScript 定义了核心类型：

ts复制export interface MaterialMeta {
  id: string;            // 物料唯一标识，如 'form-input'
  name: string;          // 物料显示名
  version: string;       // 物料版本，遵循 semver
  category: 'layout' | 'form' | 'data' | 'custom';
  remote: {
    entry: string;       // 远程模块入口 URL，如 http://cdn.xxx.com/admin/remoteEntry.js
    scope: string;       // MF 容器名，对应 ModuleFederationPlugin 里的 name
    module: string;      // 被暴露的模块路径，如 './MaterialInput'
  };
  props?: PropSchema[];  // 属性协议，搭建器根据它生成表单面板
  events?: EventSchema[]; // 事件协议，说明该组件能触发哪些事件
  defaultSize?: { width: number; height: number };
}

export interface PropSchema {
  key: string;
  label: string;
  type: 'string' | 'number' | 'boolean' | 'select' | 'json';
  options?: { label: string; value: string | number }[];
  defaultValue?: unknown;
}

export interface EventSchema {
  name: string;          // 事件名，如 'onChange'
  params: string[];      // 事件参数，如 ['value', 'ctx']
}

为什么要单独抽出 material-schema 这个包？因为搭建器（builder-app）、渲染器（main-app）、物料库（design-system 里的物料实现）三端都要用到这套类型。如果类型散落在各个应用里，改一个字段就要同时改三个地方，还容易漏。抽出独立包之后，schema 就是整个物料体系的数据契约，三端只认这一个版本。

3.2 物料注册表与 MF 的 remote 关系

有了 schema，还需要一个地方维护"哪些物料是当前可用的"。这就是 material-registry 的职责。它本质是一个 Record<string, MaterialMeta>，但有一个重要特性：物料的远程地址不是写死的前端常量，而是从配置中心动态读取的。

物料注册表里记录的是 MF 的 remote 信息。每一个物料都指向某个子应用暴露出来的模块。比如运营后台子应用（admin-app）暴露了人员选择器，数据看板子应用（dashboard-app）暴露了图表组件。这些模块分散在不同子应用里，但通过物料注册表统一暴露给搭建器。

这个设计解决了一个关键问题：物料不需要提前编译进搭建器。搭建器只是知道"存在一个 id 为 user-selector 的物料，它长这样，属性面板需要渲染这些字段"。至于组件代码在哪里，搭建器不管，渲染的时候才通过 MF 动态加载。

material-registry 本身也通过 MF 的 shared 机制在应用之间共享。主应用启动时加载注册表，builder-app 也加载同一个实例，所以两边的物料列表永远是一致的，不会出现"搭建器里能看到，渲染器里却加载不出来"的错位。

3.3 低代码页面运行时如何解析并渲染物料

渲染链路是整个低代码平台的临门一脚。搭建器把页面画布上的物料实例序列化成 JSON 表单，存到服务端。线上用户访问页面时，渲染器拿到这份 JSON，逐层解析，根据每个节点的物料 id 在注册表里找到 MaterialMeta，再动态加载对应的远程组件。

我们封装了一个 RemoteComponentLoader，核心逻辑如下：

ts复制const moduleCache = new Map<string, Promise<any>>();

async function loadRemoteComponent(meta: MaterialMeta): Promise<ComponentType> {
  const cacheKey = `${meta.id}@${meta.version}`;
  if (moduleCache.has(cacheKey)) {
    return moduleCache.get(cacheKey)!;
  }

  const loadPromise = (async () => {
    // 1. 动态注入 <script src={entry}> 加载 MF 容器
    await loadScript(meta.remote.entry);

    // 2. 从 window 上取到容器并初始化
    const container = window[meta.remote.scope];
    await container.init(
      __webpack_share_scopes__.default // 关键：把当前应用的 shared scope 传进去
    );

    // 3. 通过容器加载具体模块
    const factory = await container.get(meta.remote.module);
    const Component = factory().default;
    return Component;
  })();

  moduleCache.set(cacheKey, loadPromise);
  return loadPromise;
}

这段代码有几个细节值得展开。

container.init 这一步非常关键。MF 的远程模块不是一个独立的函数，它需要和当前应用的 shared scope 打通，这样远程组件里的 import React from 'react' 才能拿到主应用里那份 React 实例。如果不调 init，或者 __webpack_share_scopes__.default 没有提前准备好，远程组件会尝试加载自己的依赖副本，轻则体积膨胀，重则 React 双实例报错。

还有模块缓存。我们按 物料 id + 版本 做缓存，不只为了性能，更是为了保证页面里同一个物料组件只初始化一次，避免重复 init 导致运行时状态错乱。实际使用中，低代码页面经常一个模板里同一个表格组件渲染二十多次，如果没有这个缓存，页面会卡到没法用。

渲染器拿到组件后，根据 props 协议生成配置并传入组件，同时把事件处理器做一层映射绑定：

tsx复制function MaterialNode({ node }: { node: SchemaNode }) {
  const meta = getMaterialById(node.materialId);
  const Component = useRemoteComponent(meta);

  const handlers = useMemo(() => {
    return mapEventToHandler(node.events, appBus);
  }, [node.events]);

  return (
    <Component
      {...node.props}
      {...handlers}
      style={{ width: node.size.width, height: node.size.height }}
    />
  );
}

到这里，低代码平台的"物料化"闭环就算跑通了：搭建器配置 schema → 注册表管理元信息 → 渲染器通过 MF 动态加载组件。

4. Module Federation 运行时链路里最容易被忽略的细节

4.1 共享依赖的 singleton 配置：不是复制粘贴就完事

MF 的 shared 配置，表面看就是一个数组，实际坑很多。我们最终的配置长这样：

js复制// webpack.shared.js
const deps = require('./package.json').dependencies;

module.exports = {
  shared: {
    react: { singleton: true, requiredVersion: deps.react, eager: true },
    'react-dom': { singleton: true, requiredVersion: deps['react-dom'], eager: true },
    'react-router-dom': { singleton: true, requiredVersion: deps['react-router-dom'] },
    '@emotion/react': { singleton: true, requiredVersion: deps['@emotion/react'] },
    axios: { singleton: true, requiredVersion: '*' }
  }
};

这里一个非常容易踩的误区是：只在 host 里配置 shared 是不够的，remote 也必须配置一份。 因为 MF 的 shared 解析是双向的。host 加载 remote 模块时，remote 模块内部执行 import React from 'react'，webpack 会先检查 host 的 shared scope 里有没有可用的 React；如果 remote 自己的构建配置里没有声明 shared，它的 React 会被打包进产物，等于没有参与共享。

singleton 的含义也要说清楚。它不是说"这个库全局只能有一份"，而是说"当出现多份时，优先使用最顶层那一份，并且提供一个版本提示，保证拿到的是单例"。对 React 这种有内部全局状态的库，singleton 必须开；对工具函数库如 lodash-es，开不开影响不大。

requiredVersion 是另一个容易理解错的地方。它是在运行时校验版本，而不是构建时。如果 remote 声明需要 React 18.2.0，host 提供的是 18.3.1，那么 webpack 会打一个 console warning，然后在共享池里找更接近的版本，找不到才 fallback 到 remote 自己打包的副本。所以版本校验是一个协商过程，不是强约束。

eager: true 只对 host 里同步消费的包开启。如果主应用在入口文件就 import React，那 React 的 shared 模块需要在构建后的初始 chunk 里同步存在，否则会报 "Shared module is not available for eager consumption"。异步加载的包不需要 eager，加了反而增加初始体积。

4.2 跨应用数据通信与事件总线

微前端之间怎么通信，是网上问得最多的问题之一。MF 官方没有提供现成的通信方案，只有 shared 机制可以共享模块。我们基于 shared 做了一层自己的事件总线 runtime-store 包，放在 packages/ 下面。

appBus 是一个极简的发布订阅实现，底层挂载在 window 上，但通过 shared 保证多应用拿到的是同一个模块实例：

ts复制// packages/runtime-store/src/bus.ts
type Handler = (payload: unknown) => void;

class AppBus {
  private listeners = new Map<string, Set<Handler>>();

  on(event: string, handler: Handler): () => void {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set());
    }
    this.listeners.get(event)!.add(handler);
    return () => this.off(event, handler);
  }

  off(event: string, handler: Handler): void {
    this.listeners.get(event)?.delete(handler);
  }

  emit(event: string, payload: unknown): void {
    this.listeners.get(event)?.forEach((handler) => {
      try {
        handler(payload);
      } catch (err) {
        console.error(`[appBus] handler error on "${event}"`, err);
      }
    });
  }
}

export const appBus = new AppBus();

为什么不用 window.dispatchEvent 那套原生 CustomEvent？因为原生事件在 window 上是全局曝光的，事件名容易冲突，而且 payload 在传递过程中会被序列化到事件对象里，遇到复杂对象偶尔会丢失原型。自己封装一层，事件名天然带命名空间，handler 直接持有引用，传对象不会序列化丢失。

除了事件总线，我们还把全局用户信息、权限点、应用配置放进了 runtime-store 包里，通过 MF 的 shared 在多个应用间共享同一个 store 实例。注意：这个 store 是"低频全局数据"的共享方案，不要把所有 React 状态都往里塞。高频状态（比如表单输入）还是留在各子应用本地，跨应用通信只传递"用户切换了部门""配置了新的权限"这类事件。

4.3 样式隔离：我们最后放弃了一部分"严格隔离"

很多人用 MF 之后最不安心的就是样式隔离。MF 不像 qiankun 那样有 CSS 沙箱，它认为样式隔离是"应用自己负责的事"。我们一开始想在主应用里给每个子应用包一层 Shadow DOM，试了两天就放弃了。原因很实际：我们的远程物料用的是 Emotion CSS-in-JS，Emotion 默认把 style 标签插到 document.head，在 Shadow DOM 里渲染时，样式全部失效，除非给 Emotion 配置专门的 container，但每个物料组件还得感知自己被放在 Shadow DOM 里。

最终我们约定了一套轻量方案，不追求绝对隔离：

• 子应用各自的业务样式，类名统一加应用前缀，比如 .admin-user-table，这个靠团队约束 + review 卡控。
• design-system 组件库的样式用 Emotion 生成带 hash 的类名，天然不冲突。
• 全局 reset、字体、CSS 变量等影响基础排版的样式只由主应用加载。
• 子应用里的 Body 级样式（比如设置 body { background }）通过主应用暴露的 theme API 设置，不允许子应用直接写 body 选择器。

这个方案没法做到 qiankun 那种严格隔离，但对我们这种内部系统完全够用。真遇到完全不可控的第三方组件，我们还有兜底手段——把那个组件单独用 iframe 包一层。不过这种场景极少，目前只遇到过一个老旧的富文本编辑器，而且它本身的问题也不是样式冲突，是全局事件污染。

5. 五个真实踩坑记录与完整排查过程

5.1 坑一：出现两个 React 实例导致 Hooks 报错

这个坑几乎每个玩 MF 的人都会遇到。我们是在低代码平台接入远程物料时爆的：物料组件在搭建器里渲染正常，但应用发布后，线上页面打开物料直接报 Invalid hook call。React 官方对这类报错只会提示你"可能存在两个 React 副本"。

排查链路是这样走的。第一步，先在浏览器控制台执行 document.querySelectorAll('script') 看加载了哪些 JS，确认只加载了一个 remoteEntry。第二步，在子应用构建产物里搜 react.production.min.js，发现物料组件被 exposes 出去的 chunk 里硬生生打包了一份 React。这就说明 shared 没有生效——但配置里确实写了的。第三步，检查 pnpm-lock 文件，发现 admin-app 和 main-app 依赖的 React 版本虽然都是 ^18.2.0，但解析出来的实际版本一个是 18.2.0，一个是 18.2.61，webpack 在共享协商时认为版本不够接近，于是选择了 fallback 到本地副本。

修复：用 catalog 把所有子应用 React 锁定到完全一致的版本，同时在 remote 和 host 两端的 ModuleFederationPlugin 配置里都加上 requiredVersion 和 singleton。这里要强调，两边配置必须一致，否则协商逻辑会乱。

5.2 坑二：发布后远程入口被浏览器缓存

这个坑躲过了开发环境，栽在了生产环境。运营配置的新物料页面发布后，用户端过了十几分钟刷新还是看不到。我打开 Network 面板一看，remoteEntry.js 的响应状态是 200 (from disk cache)——文件根本没发请求。

MF 的远程入口文件默认是固定文件名，比如 remoteEntry.js。浏览器对这个文件的缓存策略会参考服务器的 Cache-Control，但很多时候 index.html 已经设置了长缓存，remoteEntry 也跟着被缓存了。

我们最终用三层方案解决：一是构建时给 remoteEntry 文件加上内容 hash，改成 remoteEntry.7f3a1b.js；二是主应用维护一个 manifest 文件记录当前各子应用 remoteEntry 的真实地址，index.html 只加载 manifest，manifest 动态指向带 hash 的入口；三是在发布流水线里对 *.js 注入 no-cache 头，保证入口文件每次都能重新协商。

注意，只改 remoteEntry 文件名还不够，远程模块里被 exposes 的 chunk 同样可能被缓存。所以子应用的构建产物统一走带 hash 的文件名是硬性要求，不能让任何 chunk 用固定名覆盖。

5.3 坑三：物料 schema 传递时函数被 JSON 序列化丢失

这个坑属于低代码平台特有。搭建器里，运营配置了一个搜索表单，字段联动规则写了个 onChange 函数——当用户选择"按部门筛选"时，另一个字段的 options 要动态变化。保存配置后，渲染器打开页面，联动完全没有生效，控制台显示 onChange is not a function。

我们的链路是：搭建器把 schema 序列化成 JSON 存库，页面访问时渲染器从接口拉取 JSON 再渲染。JSON 天生不支持函数，JSON.stringify 会直接把函数字段丢弃。但问题是电商平台搭建器里写函数非常自然，没人会意识到函数没法通过 JSON 传输。

修复方案我们没有选择"把函数转字符串再 eval"，而是改成了"事件描述"方案。用户在搭建器里配置联动时，不再写函数，而是选择"当字段 A 变化时，执行动作 B"：

json复制{
  "events": [
    {
      "trigger": "onChange",
      "action": "setFieldOptions",
      "config": {
        "target": "departmentList",
        "fetch": "fetchDepartmentsByOrg"
      }
    }
  ]
}

渲染器内部维护一张 action 映射表，setFieldOptions 对应的处理函数在渲染器本地注册。这样 schema 里只存纯 JSON，没有函数，稳定跨端传输。低代码平台最好一开始就按照"事件驱动描述"的模式设计，不要允许用户在 schema 里写函数。

5.4 坑四：remote 加载顺序导致白屏和 shared module 报错

有一次我们新增了一个远程物料，主应用打开那个物料页面时白屏，控制台报 Shared module is not available for eager consumption。当时的第一反应是 shared 配置写错了，但检查了一圈配置没问题。后来发现，报错只发生在首屏直出场景——主应用入口处用同步 import 引用了那个物料组件，而物料组件是异步 remote 模块，这就导致在共享依赖初始化之前，代码就尝试消费共享作用域。

MF 处理 "eager" 和 "async" 模块的加载时序是有讲究的。eager: true 的包会被打进初始 chunk，同步可用；异步加载的包必须在初始化完成后再去 container.get()。我们的物料组件走的是异步 remote，不应该在主应用同步代码路径里直接 import。

解法有两种。第一种是给 all shared 加 eager: true，但这样会把所有共享依赖都同步打到初始 bundle，体积直接爆炸，不可取。第二种就是正确的玩法：把物料加载改造成异步组件，用 React.lazy + Suspense 包一层，确保 remote 模块一定在异步边界内加载。同时，对真正需要同步的 react、react-dom 保留 eager: true，其余全部走异步。

5.5 坑五：弹层组件挂载错位与样式失效

低代码页面上线后，运营反馈一个弹窗表单在部分页面上出现样式错乱。具体表现是：弹层背景透明、按钮大小异常、弹窗位置偏上。明显是 CSS 没有生效。

排查后发现，问题出在远程物料组件里的 Modal 组件上。我们用的是 antd 的 Modal，默认通过 createPortal 把弹层渲染到 document.body 下。物料组件加载时，Emotion 生成的样式被插入 document.head，但 Modal 组件的样式是 antd 的全局样式，依赖主应用的 CSS 变量和 reset。当物料组件所在子应用的 CSS 前缀和主应用不一致时，弹层样式就崩了。

根本原因是：弹层组件跨出了 MF 的模块作用域，挂到了 DOM 树的另一个位置，样式的"就近原则"失效了。 解决方案有两步：一是在物料组件设计规范里明确，所有弹层类组件必须使用 portal 到 document.body，并且依赖的样式必须使用 Emotion 的 hash 类名，不能依赖 antd 全局样式；二是在 design-system 里封装一套统一的弹层组件，内部加一个可配置的 getContainer 属性，在主应用场景下传主应用的根节点，在物料场景下传物料渲染容器。

这个坑踩完，我们意识到微前端环境下的组件库不能只是"能用"，它对全局副作用（弹层、消息通知、Dubious 工具）的处理要比普通应用更挑剔。

6. 落地后的收益与下一步规划

6.1 构建与发布效率的实际变化

架构切换前后，我们统计过一组数字：

这个变化最直接的价值不是节省了多少秒构建时间，而是让"小步快跑"变成可能。以前改一行公共组件要发整个平台，现在只在 design-system 里发一个补丁版本，受影响的子应用按需升级，风险完全可控。像"运营想要调整某个配置页的布局"这种需求，现在运维同学在搭建器里拖一拖就能上线，不需要排队等开发排期。

6.2 团队协作模式的变化

架构落地后，团队从"所有人改一个仓库"变成了"一个小组只关心一两个子应用"。admin-app 对应运营后台小组，dashboard-app 对应数据小组，builder-app 和 material-registry 归中台小组维护。代码归属清晰之后，Code Review 的效率也上来了，评审人只需要看自己熟悉领域的 diff，不需要全局理解上下文。

另一个变化是版本发布权限的收敛。共享包（design-system、material-schema）的发布权限收归中台小组，业务子应用没有直接改动共享包的权限。这样即使某天某个子应用改坏了，也不会直接污染其他子应用的依赖。

6.3 后续规划

这套架构跑通之后，我们已经在规划下一步了。

第一个方向是物料中台化。现在物料注册表还是一个静态 JSON 集合，后面想做成带版本灰度、AB 实验、上下线管理的中台服务，所有物料的上线和下线都走配置中心，不重新发版。

第二个方向是拥抱更多构建工具。MF 官方生态已经支持 Vite 侧的插件，我们准备把 builder-app 从 webpack 迁移到 Vite，验证一下 MF 在混合构建工具场景下的稳定性。如果这台能跑通，后面技术选型的自由度就更大了。

第三个方向是完善低代码渲染器的运行时沙箱能力。虽然现在自家物料足够安全，但未来如果开放第三方物料接入，就必须考虑非信任代码的隔离执行，可能需要引入 iframe 级沙箱与 MF 远程模块结合的一套方案。

如果你们团队正在评估类似的架构，我的建议是先做一个小范围试点，用真实业务页面跑通完整链路再推广。架构本身不复杂，复杂的是组织协作习惯的迁移。