React Renderer 分离的多平台架构

老王以为
2,281 阅读15分钟

之前做过一个在线海报编辑器——用户在浏览器里拖拽元素、改文字、调颜色，最后导出 PNG。业务跑得不错，但老板有了新的想法。

"我们要出微信小程序版本。"他在周会上说。

我算了算工作量。海报编辑器的前端有将近两百个组件——画布、图层面板、属性面板、文字编辑器、图片裁剪器……这些组件全部是基于 React + DOM 写的。小程序没有 DOM，没有 div 和 span，只有 view 和 text。两百个组件，每一个都要重写。

我说："大概需要六个月。"

老板说："给你三个月。"

三个月过去了，我们勉强出了一个 MVP。但噩梦才刚刚开始。用户反馈 web 版和小程序版的功能不一致——web 上能用的滤镜，小程序上没有；小程序上的某个动效，web 上没有。每次 web 端加一个新功能，我们都得评估"要不要同步到小程序"——同步的话意味着双倍工作量，不同步的话用户投诉。

更离谱的是，老板后来又说："我们还要出桌面版。"用 Electron 做。Electron 有 DOM，看起来应该可以直接复用 web 版的代码。但问题是——Electron 的渲染进程和主进程之间的通信模型和浏览器完全不同，文件系统访问、打印、导出 PDF……这些能力都需要重新封装。

到那一刻，我终于理解了一个痛苦的事实：我们的组件逻辑和渲染平台是紧紧耦合在一起的。两百个组件，每一个都知道自己运行在浏览器里，每一个都直接调用 document.createElement 和 addEventListener。当需要换一个平台时，没有抽象层可以依赖，只能从最底层重新盖楼。

后来我在 React 的源码的 packages/react-reconciler/src/ReactFiberConfig.js 看了很久。那文件只有二十行，只有一句有用的代码：

throw new Error('This module must be shimmed by a specific renderer.');

一行 throw，背后藏着一个架构设计的核心判断：把"怎么更新组件"和"怎么操作平台"彻底分开。这就是 Reconciler / Renderer 分离的精髓——一份协议，多端运行。

一、当组件逻辑和渲染平台焊死在一起

上面那个海报编辑器的问题，本质是一个平台耦合的问题。我们的两百个 React 组件里，<Canvas /> 组件内部直接调用了 canvas.getContext('2d')，<TextEditor /> 直接用了 contentEditable 和 document.execCommand，<LayerPanel /> 依赖了 CSS Flexbox 的拖拽排序。这些代码在浏览器里跑得挺好，但它们和 DOM 是焊死的。

这种模式的问题，在只有一个平台的时候不明显。但一旦需要支持多个平台，痛苦指数级放大：

第一，代码重复。 同样的组件逻辑，在浏览器里写一遍，在小程序里写一遍，在桌面端写一遍。不是"复制粘贴"那种重复——是"用不同的 API 实现同样的功能"这种更隐蔽、更昂贵的重复。

第二，行为不一致。 三个平台，三套实现，三个 bug 集合。用户报告"小程序上的文字编辑器有问题"，修完小程序的，发现 web 上也有类似的问题——但代码完全不同，修复不能复用。

第三，功能不对齐。 web 端加了一个新滤镜，需要评估"小程序 Canvas 支不支持这种混合模式"。不支持？那这个版本小程序用户用不上。支持？需要额外两周开发。产品决策被技术约束绑架。

第四，测试爆炸。 三个平台，三套测试用例。改一个通用逻辑，需要跑三套测试。CI 时间从 10 分钟变成 30 分钟，再变成一个小时。

根本原因是架构上缺少一个平台抽象层。组件直接和平台 API 打交道，而不是通过一个中间层来间接访问。React 没有犯这个错误。从第一天起，React 就把"组件怎么更新"和"更新结果怎么画到屏幕上"分成了两个独立的层次。

二、Reconciler 是大脑，Renderer 是双手

React 的架构可以粗暴地切成两半：

  • Reconciler（协调器）：负责"决定什么需要改变"。它比较新的虚拟树和旧的虚拟树，找出差异，生成一个副作用列表（"这个节点要插入"、"那个节点要删除"、"这个属性要更新"）。它完全不知道 DOM 是什么、Native 视图是什么。
  • Renderer（渲染器）：负责"执行改变"。它接收 reconciler 生成的副作用列表，翻译成平台特定的操作。在浏览器里，这些操作是 appendChild、setAttribute、removeChild。在 React Native 里，这些操作是 UIManager.createView、UIManager.updateView。在测试环境里，这些操作可能只是一次内存中的对象修改。

它们之间的契约，就是 HostConfig。Reconciler 在需要操作平台时，调用 HostConfig 中的函数，而不是直接操作 DOM 或 Native API。

这组接口大约包括：

函数作用DOM 实现Native 实现
createInstance(type, props)创建平台元素document.createElement(type)UIManager.createView(tag, class, props)
createTextInstance(text)创建文本节点document.createTextNode(text)UIManager.createView(tag, RCTText, {text})
appendChild(parent, child)添加子节点parent.appendChild(child)UIManager.manageChildren(tag, [], [child])
insertBefore(parent, child, before)插入子节点parent.insertBefore(child, before)UIManager.manageChildren(tag, [], [child], [index])
removeChild(parent, child)移除子节点parent.removeChild(child)UIManager.manageChildren(tag, [child], [])
commitUpdate(instance, updatePayload)更新属性node.setAttribute(key, val)UIManager.updateView(tag, props)
finalizeInitialChildren()初始化完成绑定事件监听器无操作

Reconciler 永远不会直接调用 document.createElement。它调用 createInstance——这个函数由 renderer 提供。如果 renderer 是给浏览器用的，createInstance 内部调用 document.createElement。如果 renderer 是给 React Native 用的，createInstance 内部调用 UIManager.createView。

同样的 reconciler 大脑，换一双不同的手，就能在不同的平台上工作。

三、源码里的协议与实现

3.1 ReactFiberConfig.js —— 一行 throw，一份契约

打开 packages/react-reconciler/src/ReactFiberConfig.js：

// https://github.com/facebook/react/blob/main/packages/react-reconciler/src/ReactFiberConfig.js
/**
 * We expect that our Rollup, Jest, and Flow configurations
 * always shim this module with the corresponding host config
 * (either provided by a renderer, or a generic shim for npm).
 *
 * We should never resolve to this file, but it exists to make
 * sure that if we *do* accidentally break the configuration,
 * the failure isn't silent.
 */

throw new Error('This module must be shimmed by a specific renderer.');

二十行代码，九成是注释。唯一有用的代码是那行 throw。

但正是这行 throw，定义了整个架构的契约边界。Reconciler 包的源码中，所有需要操作平台的地方，都 import 自这个模块：

import {
  createInstance,
  appendChild,
  removeChild,
  commitUpdate,
  // ...
} from './ReactFiberConfig';

注意路径——'./ReactFiberConfig'，不是 '../react-dom-bindings/...'。Reconciler 不依赖任何具体的 renderer。它依赖的是一个抽象的接口。

这个接口的"具体实现"，是在构建时通过 Rollup 的模块别名（alias）注入的。看 react-dom 的构建配置：所有对 react-reconciler/src/ReactFiberConfig 的导入，都被重定向到 react-dom-bindings/src/client/ReactFiberConfigDOM.js。而 react-native-renderer 的构建配置，则把同样的导入重定向到它自己内部的 Native HostConfig。

这说明：同一份 reconciler 源码，被编译到了 react-dom 包里就变成了操作 DOM 的版本，被编译到了 react-native-renderer 包里就变成了操作 Native 视图的版本。代码是一样的，只是链接时的接口实现不同。

3.2 ReactFiberConfigDOM.js —— 6669 行的 DOM 操作百科全书

如果说 ReactFiberConfig.js 是一份"协议宣言"，那么 ReactFiberConfigDOM.js 就是协议的"完整实现"。6669 行代码，几乎是整个 React DOM 渲染器的全部平台相关逻辑。

// https://github.com/facebook/react/blob/main/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js
export function createInstance(
  type: string,
  props: Props,
  rootContainerInstance: Container,
  hostContext: HostContext,
  internalInstanceHandle: Object,
): Instance {
  const ownerDocument = getOwnerDocumentFromRootContainer(
    rootContainerInstance,
  );
  const domElement: Instance = ownerDocument.createElement(type);
  // ... 属性处理、事件绑定、ref 关联
  precacheFiberNode(internalInstanceHandle, domElement);
  updateFiberProps(domElement, props);
  return domElement;
}

export function createTextInstance(
  text: string,
  rootContainerInstance: Container,
  hostContext: HostContext,
  internalInstanceHandle: Object,
): TextInstance {
  const ownerDocument = getOwnerDocumentFromRootContainer(
    rootContainerInstance,
  );
  const textNode: TextInstance = ownerDocument.createTextNode(text);
  precacheFiberNode(internalInstanceHandle, textNode);
  return textNode;
}

export function appendChild(parentInstance: Instance, child: Instance | TextInstance): void {
  parentInstance.appendChild(child);
}

export function insertBefore(
  parentInstance: Instance,
  child: Instance | TextInstance,
  beforeChild: Instance | TextInstance,
): void {
  parentInstance.insertBefore(child, beforeChild);
}

export function removeChild(
  parentInstance: Instance,
  child: Instance | TextInstance,
): void {
  parentInstance.removeChild(child);
}

export function commitUpdate(
  domElement: Instance,
  updatePayload: Array<mixed>,
  type: string,
  oldProps: Props,
  newProps: Props,
  internalInstanceHandle: Object,
): void {
  // 应用属性差异到 DOM 节点
  updateProperties(domElement, updatePayload, type, oldProps, newProps);
  // 更新 Fiber 节点上缓存的 props
  updateFiberProps(domElement, newProps);
}

这些函数看起来很简单——不就是包装了一下 DOM API 吗？但魔鬼在细节里。

createInstance 里的 precacheFiberNode。这个函数把 Fiber 节点和 DOM 节点之间的映射关系缓存到一个全局 Map 里。当 React 需要"从 DOM 事件找到对应的 Fiber 节点"时（比如事件委托），它不需要遍历 Fiber 树——直接从 Map 里查。这个 Map 的管理完全在 HostConfig 层完成，reconciler 不操心。

commitUpdate 里的 updateProperties。DOM 属性更新不是简单的 element.setAttribute。不同属性有不同的更新逻辑——style 需要解析 CSS 字符串，checked 和 value 需要特殊处理以保持一致性，事件监听器需要委托到 root 节点而不是直接绑定。这些 DOM 特有的复杂性，全部被封装在 HostConfig 里。Reconciler 只需要说"更新这个节点的属性"，具体怎么更新，HostConfig 决定。

这 6669 行代码里，大约只有 5% 是上面这种"直接代理 DOM API"的函数。剩下的 95% 都是DOM 特有的复杂逻辑——事件系统、属性处理、hydration、表单元素特殊行为、资源预加载、无障碍属性……所有这些平台特定的细节，都被 HostConfig 吞掉了，reconciler 完全不知情。

3.3 ReactFiberConfigNoop.js —— 能力组合的艺术

如果说 ReactFiberConfigDOM.js 是"全功能 renderer"的典范，那么 ReactFiberConfigNoop.js 则是"按需组合能力"的精妙设计。

Noop renderer 是 React 内部测试用的渲染器。它不操作任何真实平台——没有 DOM，没有 Native 视图，所有操作都在内存中进行。但测试场景有不同的需求：有时需要模拟 mutation（插入/删除/更新），有时需要模拟 persistence（快照/恢复），有时需要 hydration，有时不需要。

React 的做法不是写一个大而全的 Noop Config，而是把它拆成多个能力模块：

// https://github.com/facebook/react/blob/main/packages/react-noop-renderer/src/ReactFiberConfigNoop.js
export * from './ReactFiberConfigNoopHydration';
export * from './ReactFiberConfigNoopScopes';
export * from './ReactFiberConfigNoopTestSelectors';
export * from './ReactFiberConfigNoopResources';
export * from './ReactFiberConfigNoopSingletons';
export * from './ReactFiberConfigNoopNoMutation';
export * from './ReactFiberConfigNoopNoPersistence';

export type HostContext = Object;
export type TextInstance = { text: string, id: number, ... };
export type Instance = { type: string, id: number, ... };
export type Container = { rootID: string, children: Array<...>, ... };

看看这些文件名：

模块功能
ReactFiberConfigNoopHydration.jshydration 能力（服务端渲染后客户端激活）
ReactFiberConfigNoopScopes.jsscope API 支持
ReactFiberConfigNoopTestSelectors.js测试选择器 API
ReactFiberConfigNoopResources.js资源预加载（link preload/prefetch）
ReactFiberConfigNoopSingletons.jssingleton 模式（HTML/HEAD/BODY）
ReactFiberConfigNoopNoMutation.js不支持 mutation——空实现
ReactFiberConfigNoopNoPersistence.js不支持 persistence——空实现

主文件通过 export * 把所有模块的能力组合在一起。如果需要创建一个"支持 mutation 但不支持 persistence"的测试 renderer，createReactNoop.js 会覆盖特定的导出：

// https://github.com/facebook/react/blob/main/packages/react-noop-renderer/src/createReactNoop.js
// 覆盖 NoMutation 的导出，换成实际支持 mutation 的版本
Object.assign(fiberConfig, mutationConfig);
// 覆盖 NoPersistence 的导出，换成实际支持 persistence 的版本（如果需要）
if (usePersistentMode) {
  Object.assign(fiberConfig, persistentConfig);
}

这是一种 能力组合（capability composition） 的设计模式。每个能力是一个独立的模块，renderer 通过选择性地导入和覆盖这些模块来声明自己支持什么、不支持什么。

3.4 ReactFiberConfigWithNoMutation.js —— 不支持的能力怎么表达

在 react-reconciler/src/ 目录下，有一组 ReactFiberConfigWithNo*.js 文件：

ReactFiberConfigWithNoHydration.js
ReactFiberConfigWithNoMicrotasks.js
ReactFiberConfigWithNoMutation.js
ReactFiberConfigWithNoPersistence.js
ReactFiberConfigWithNoResources.js
ReactFiberConfigWithNoScopes.js
ReactFiberConfigWithNoSingletons.js
ReactFiberConfigWithNoTestSelectors.js
ReactFiberConfigWithNoViewTransition.js

看看 ReactFiberConfigWithNoMutation.js 的内容：

// https://github.com/facebook/react/blob/main/packages/react-reconciler/src/ReactFiberConfigWithNoMutation.js
// Renderers that don't support mutation can re-export everything from this module.

function shim(...args: any): empty {
  throw new Error(
    'The current renderer does not support mutation. ' +
      'This error is likely caused by a bug in React. ' +
      'Please file an issue.',
  );
}

export const supportsMutation = false;
export const appendChild = shim;
export const removeChild = shim;
export const commitUpdate = shim;
// ... 更多 mutation 函数都是 shim

这是 Null Object Pattern 的应用。当某个平台不支持 mutation 时（比如一些纯声明式的渲染目标），reconciler 不会去调用这些函数——因为它会检查 supportsMutation 标志。但如果代码路径有 bug，不小心调到了这些函数，shim 会立刻抛出一个清晰的错误，而不是静默失败或产生 undefined behavior。

这种设计体现了 React 团队的一个工程判断：不支持的功能，不应该用"不导出"来表达，而应该用"导出但标记为不支持"来表达。因为"不导出"会导致导入时得到 undefined，而 undefined 被调用时的错误信息极其晦涩。shim 函数明确的错误信息，能节省数小时的调试时间。

同时，supportsMutation = false 这个标志位让 reconciler 可以在运行时检测平台能力。如果 renderer 不支持 mutation，reconciler 会选择走 persistence 路径（先创建新树，再整体替换）。这就像一个聪明的管家——如果家里没有拖把（mutation），它会改用吸尘器（persistence）来打扫。

3.5 ReactDOMRoot.js —— reconciler 的组装现场

看看 react-dom 包怎么把 reconciler 和 HostConfig 组装在一起。

// https://github.com/facebook/react/blob/main/packages/react-dom/src/client/ReactDOMRoot.js
import {
  createContainer,
  updateContainer,
  flushSync,
} from 'react-reconciler/src/ReactFiberReconciler';

// ReactFiberReconciler 内部会 import './ReactFiberConfig'
// Rollup 构建时，这个导入被替换为 react-dom-bindings 的 ReactFiberConfigDOM

export function createRoot(container: Element | Document | DocumentFragment): RootType {
  const root = createContainer(
    container,           // 容器 DOM 节点
    ConcurrentRoot,      // root 类型
    null,                // hydration callbacks
    false,               // isStrictMode
    null,                // concurrent updates by default
    identifierPrefix,
    onUncaughtError,
    onCaughtError,
    onRecoverableError,
    null,
  );
  // ...
  return {
    render(children) { updateContainer(children, root, null); },
    unmount() { updateContainer(null, root, null); },
    _internalRoot: root,
  };
}

createRoot 看起来只是在调用 react-reconciler 的 createContainer。但关键是——createContainer 的实现（在 ReactFiberReconciler.js 中）内部会调用 HostConfig 的函数。比如创建 root fiber 时，它需要知道怎么创建容器实例——这就调到了 createInstance。

而在 react-dom 的构建产物中，这个 createInstance 来自 ReactFiberConfigDOM.js，它内部调用的是 document.createElement。如果构建的是 react-native-renderer，同一个 createContainer 调用的是 Native 的 UIManager.createView。

这就是"一份协议，多端运行"的本质——同一份 reconciler 源码，链接不同的 HostConfig 实现，就得到了不同的 renderer。

四、能力矩阵——各平台 renderer 的能力差异

不同的 renderer 对 HostConfig 协议的实现程度不同。有些功能某些平台天然不支持，有些则是设计上的取舍。

能力react-domreact-nativereact-noop含义
基本树操作✓✓✓所有平台都支持
supportsMutation✓✓可选增量更新节点
supportsPersistence✗✗可选整体替换树
supportsHydration✓✗✓SSR 后客户端激活
资源预加载✓✗✓link preload/prefetch
Singletons✓✗✓HTML/HEAD/BODY 特殊处理

注意 react-dom 的 supportsPersistence = false。DOM 是天然支持 mutation 的——可以随时修改一个元素的属性或插入一个子节点。所以 react-dom 选择走 mutation 路径，不走 persistence 路径。

而某些平台（比如一些声明式的 UI 框架）可能只支持 persistence——只能提交一整棵新的树来替换旧的，不能单独修改某个节点。这种平台会设置 supportsMutation = false, supportsPersistence = true，reconciler 会自动切换算法。

五、从 React 的协议设计到我们的工程

用协议隔离变化

React 的 Reconciler / Renderer 分离，本质是一种协议驱动架构（Protocol-Driven Architecture）。Reconciler 定义"我需要什么操作"，Renderer 实现"这些操作怎么在平台上执行"。两者通过 HostConfig 协议通信。

这种架构的价值在于：任何一方都可以独立演化。Reconciler 可以升级调度算法（Fiber → Concurrent → 未来的什么），只要 HostConfig 接口不变，所有 renderer 都不需要改。反过来，renderer 可以添加新的平台能力（比如 react-dom 新增了 View Transition API 支持），只要实现了 HostConfig 中对应的函数，reconciler 就能用上。

在自己的系统里，当需要支持多个平台或多个后端时，考虑定义一个核心协议：

  • 核心层定义"我需要什么操作"
  • 适配层实现"这些操作在平台 X 上怎么执行"
  • 用构建工具（Rollup alias / Webpack resolve.alias）在编译时注入具体实现
  • 对不支持的能力，提供 shim 空实现 + supportsXxx = false 标志

HostConfig 的思想不只属于 React

HostConfig 的核心思想——用一组接口函数抽象平台差异——是普适的。举几个例子：

  • 数据存储层：定义 StorageConfig 接口——createRecord、updateRecord、deleteRecord、queryRecords。Web 端实现用 IndexedDB，移动端实现用 SQLite，测试环境用内存 Map。
  • 网络请求层：定义 NetworkConfig 接口——request、upload、download。Web 端用 fetch，桌面端用 Node.js http 模块，小程序用 wx.request。
  • 文件系统层：定义 FileSystemConfig 接口——readFile、writeFile、listDirectory。Web 端用 File System Access API，桌面端用 Node.js fs，移动端用原生桥接。

关键是：业务代码只依赖接口，不依赖具体实现。实现通过构建配置注入。

协议是团队协作的契约

HostConfig 不仅是代码层面的接口，更是团队层面的契约。React 核心团队维护 reconciler，Facebook 内部团队维护 react-dom，社区维护 react-native-renderer。三方团队不需要频繁沟通——只要 HostConfig 接口不变，各自可以独立开发、独立发布。

这种"通过协议解耦团队"的模式，对于大型组织的架构设计有重要启示：

React 的做法迁移策略
HostConfig 定义 reconciler 和 renderer 的边界在团队之间定义 API 契约，而不是直接依赖对方的内部实现
supportsXxx = false 标志让 reconciler 自适应服务降级策略——后端能力不可用时，前端自动切换为简化模式
Rollup alias 在构建时注入实现CI/CD 中通过环境变量切换不同的后端实现，同一份业务代码跑在不同环境
shim 函数明确报错而非静默失败接口未实现时抛清晰错误，而不是返回 undefined 导致后续难以调试

六、好架构的本质是定义边界

回看 ReactFiberConfig.js 那行 throw new Error。二十行代码，九成注释，一行有效代码。但它定义了整个 React 多平台架构的基石。

好架构的本质不是写出多么精妙的算法，而是定义清晰的边界——什么东西属于这一层，什么东西属于那一层，层与层之间通过什么协议通信。边界定好了，每一层内部的实现可以任意替换、任意演化，而不会波及到别处。

React 的 reconciler 已经有上万行代码——调度算法、优先级系统、Fiber 树管理、副作用收集……但这些代码对"自己运行在哪个平台上"一无所知。它们只认识 HostConfig 中定义的十几个函数。就是这十几个函数，让同一份 reconciler 大脑，能够驱动浏览器 DOM、iOS/Android Native 视图、内存中的测试对象、甚至未来还没有被发明出来的新平台。

我在那个海报编辑器项目失败后，花了很多时间思考"如果重来一次，该怎么设计"。答案是：从第一天起就定义一个 RendererConfig 接口。画布操作不直接调 Canvas API，而是通过 config.createCanvasContext()。文字编辑不直接用 contentEditable，而是通过 config.createTextEditor()。当老板说"我们要出小程序版"的时候，我只需要实现一个新的小程序 RendererConfig，而不是重写两百个组件。

React 花了十年时间告诉我们一个道理：平台会变，协议永存。

avatar
文章
阅读
粉丝