很多团队第一次做页面平台时，都会把配置当成组件代码的附属物：有个 config.json 能让后台展示一下组件列表，有几个字段能让编辑器渲染表单，似乎就已经够了。

但系统复杂度一旦上来，这种看法很快就会失效。

在 MultipleSite 这套多站点页面平台里，真正稳定串起整条链路的，不是 React 组件本身，也不是某个后台页面，而是一份被多个子系统共同消费的协议。它一头连着组件资产，一头连着后台、编辑器、构建器、SSR 运行时和本地预览。没有这层协议，系统里每多一个环节，就会多一层脆弱的手工对齐；有了这层协议，页面生产才真正从“写代码”变成“运行一条可被约束的流水线”。

这篇文章主要说三件事：

为什么多子系统协作时，协议会从“辅助信息”变成“系统契约”
这份协议在仓库里到底长什么样，而不是抽象概念上的“元数据”
后台、编辑器、构建、SSR、本地预览分别如何消费同一份协议

一、当前端不止一个运行面，协议就不再是可选项

单纯做组件库时，组件源码往往就是唯一事实来源。开发者 import 一个组件，看 props 类型、读 README、跑 Demo，就可以完成大部分工作。

但页面平台不是只有开发者在消费组件。

在这个项目里，至少有 5 个子系统需要理解“一个组件到底是什么”：

后台：要把组件展示给运营，要知道它叫什么、属于哪个分类、长什么样。
编辑器：要根据配置动态生成表单，而不是为每个组件手写设置面板。
构建器：要在编译期知道组件依赖什么数据、哪些参数属于 fetch、哪些属于组件本身。
SSR 运行时：要根据构建产物和数据契约完成版本化装载。
本地预览/开发环境：要在不接后台的情况下也能读取组件定义，做本地开发和联调。

如果这 5 个系统各自从源码里“猜”组件信息，系统会很快失控。

后台会自己维护一份组件注册表，编辑器会维护另一份字段类型映射，构建器又会靠约定读取 fetch 导出，最后每次加字段、改类型、做兼容都需要通知多个系统同步修改。系统不是被复杂业务打垮，而是被重复描述同一个事实打垮。

所以，多站点页面平台真正需要的不是“让组件可配置”，而是“让配置成为唯一可信的系统契约”。

下面这张图可以概括这层关系：

这里最关键的一点是：协议不是描述“怎么实现组件”，而是描述“系统如何理解组件”。

二、这份协议在仓库里到底长什么样

在 MultipleSite 里，这层契约不是口头约定，而是明确写进了 schema 和每个组件的 config.json。

顶层的模式定义在 components/configSchema.json。从 schema 可以直接看出协议关心的，不是组件内部用什么 hook、怎么拆样式，而是这些跨系统都需要知道的字段：

{
  "version": "string",
  "fileList": ["string"],
  "key": "string",
  "name": "string",
  "preview": "string",
  "category": ["common", "store", "product"],
  "fetchArgs": {},
  "fetchData": {},
  "config": []
}

其中最核心的有 6 个：

key：组件的全局唯一标识，是后台识别、编辑器导入、构建产物命名的基础。
version：组件版本号，不只是展示字段，而是后续发布、灰度、回滚的基础单位之一。
preview：运营侧看到的预览图，解决“能不能选对组件”的问题。
category：后台筛选和组织组件列表时使用的分类信息。
fetchArgs：显式声明这个组件需要哪些注入型数据参数。
config：定义运营可以编辑哪些字段，以及这些字段该用什么控件、遵循什么规则。

如果只看 schema 还比较抽象，仓库里真实组件的配置会更直观。比如 PromotionBanner 的配置大致是这样的：

{
  "$schema": "../../../configSchema.json",
  "version": "0.0.1",
  "key": "PromotionBanner",
  "name": "促销Banner",
  "preview": "https://.../promotion-banner.png",
  "category": ["common"],
  "config": [
    {
      "key": "media",
      "type": "media",
      "label": "背景资源",
      "required": true
    },
    {
      "key": "title",
      "type": "input",
      "label": "标题"
    },
    {
      "key": "link",
      "type": "link",
      "label": "链接"
    },
    {
      "key": "mTextPosition",
      "type": "select",
      "label": "文本位置",
      "options": [
        { "label": "顶部", "value": "top" },
        { "label": "底部", "value": "bottom" }
      ]
    }
  ]
}

这份配置最大的价值，不是“让组件支持几个表单字段”，而是把一个组件从纯实现，提升成一个可被平台识别的标准化资产。系统里其他模块并不需要知道 PromotionBanner 用了什么 JSX 结构，却都可以理解它的名字、分类、展示方式、编辑入口和数据边界。

三、后台看到的不是组件源码，而是协议暴露出的资产目录

对后台来说，React 组件源码其实太底层了。

运营在页面搭建后台看到的，不应该是一堆目录名，更不应该是 TSX 文件；他需要的是一个“可选择组件目录”：每个组件有名称、分类、预览图，最好还能知道它适合用在哪些场景。

这正是 key、name、preview、category 这几个字段存在的意义。

从这个角度看，协议解决的是后台的两个核心问题：

组件如何被发现：后台扫描组件配置后，就能把它们组织成待选物料，而不需要理解组件实现细节。
组件如何被正确选择：预览图和分类让运营在视觉和语义层面识别组件，减少选错和试错成本。

这一点看起来很朴素，但它意味着系统边界发生了变化：后台管理的不是前端代码，而是被协议包装过的页面物料。

一旦系统接受这个设定，很多能力都会自然长出来，比如：

按分类筛选组件
限制特定商户只出现某些组件
在组件升级后保留旧版本，避免已有页面被强制替换
给运营展示更友好的组件描述和可视化预览

如果没有协议层，这些功能最后都只能靠硬编码表维护。那样不是做平台，而是在持续偿还同步成本。

四、编辑器最依赖协议，因为它本质上是在“翻译组件”

编辑器是整套系统里最不能直接依赖组件源码的部分。

原因很简单：组件 props 是写给工程师看的，编辑器表单是写给运营看的。这是两套完全不同的语言系统。

比如开发者能理解：

type Props = {
  media: MediaAsset;
  title?: string;
  link?: LinkValue;
  mTextPosition?: 'top' | 'bottom';
}

但运营需要看到的是：

背景：上传或选择媒体
标题：输入框
链接：链接配置器
文本位置：下拉选项

这件事在 page-editor 里是明确做成动态映射的。编辑器不是为每个组件写一套 setting UI，而是读取配置项里的 type，再把它映射成对应控件。

它支持的类型在代码里非常直接：

switch (props.value.type) {
  case 'input':
  case 'switch':
  case 'input-number':
  case 'image':
  case 'video':
  case 'select':
  case 'media':
  case 'link':
  case 'multiple-select':
  case 'group':
  case 'date-picker':
  case 'color-picker':
}

而设置面板的主体逻辑也说明了这件事：编辑器会遍历 configInterface，对每个配置项统一渲染 CompInput，而不是根据组件名写分支。

return props.configInterface.map((config, index) => (
  <CompInput
    value={ config }
    getSetting={ () => initSettings.current[config.key] }
    readOnly={ props.readOnly }
    properties={ [config.key] }
  />
));

这背后其实是一种很重要的设计转向：

如果编辑器面向组件实现编程，新增一个组件往往就意味着新增一堆表单代码。
如果编辑器面向协议编程，新增组件通常只是新增一份配置和实现，编辑器本身不用跟着改。

也就是说，协议把编辑器从“组件定制 UI 工厂”解放成了“通用协议解释器”。这是平台能扩张的关键。

下面这张图展示了这条转译链路：

协议越稳定，编辑器越通用；协议越松散，编辑器越容易退化成大量 if-else。

五、构建器最看重的不是 `config`，而是 `fetchArgs`

如果说后台和编辑器主要消费的是组件的展示信息与编辑信息，那么构建器更关心的是另一类问题：这个组件和数据依赖之间到底是什么关系。

这就是 fetchArgs 特别重要的原因。

在很多“配置驱动”系统里，数据依赖其实是藏在组件实现里的，比如写在 fetch 方法、hook、甚至副作用逻辑中。这样做短期灵活，长期的问题是构建系统无法在编译阶段理解页面的真实依赖关系。

MultipleSite 在这一步做得很硬：PageBuilder 会直接校验组件导出的 fetch 与配置里的 fetchArgs 是否匹配。

代码里的约束非常明确：

if (isFetchComponent && !componentConfigJson.fetchArgs) {
  Logger.warning("组件文件提供了 'fetch' 导出参数但是配置文件未提供 'fetchArgs'");
}
else if (!isFetchComponent && componentConfigJson.fetchArgs) {
  Logger.error("配置文件提供了 'fetchArgs' 但是组件文件未提供 'fetch' 导出参数");
}

而在真正拼装组件参数时，构建器也会按 fetchArgs 把参数拆成两部分：

一部分是给数据获取流程使用的 fetch 参数
另一部分才是传给 React 组件的展示参数

这一步的意义非常大，因为它把“组件依赖什么数据”从实现细节抬升成了显式契约。于是构建器才能做后面的事情：

在编译期发现配置和实现不一致
生成更清晰的页面依赖关系
为 SSR 或预构建阶段注入所需数据
把数据获取和组件渲染拆成更稳定的两段流程

这里有一个非常典型的工程判断：协议不只是给 UI 配表单，它更重要的作用是把原本隐性的运行时约束前移到构建期。

一旦做到这一点，系统的可靠性就会上一个台阶。很多本来要在线上请求阶段才暴露的错误，会在发布前就被识别出来。

六、SSR 和运行时真正消费的是“被协议整理过的产物”

很多人一提 SSR，会把注意力放在“服务端怎么把 React 组件渲染成 HTML”。但对页面平台来说，这其实不是最难的部分。

更关键的是：运行时如何知道某个页面版本该加载什么组件、该注入什么数据、该用什么配置解释页面结构。

从这条链路看，SSR 运行时当然不会直接去扫描源代码目录。它实际消费的是构建器根据协议整理出来的结果：

哪个组件属于哪个版本
这个版本下组件的配置长什么样
哪些参数是渲染参数，哪些参数是数据参数
页面最终对应哪些构建产物和清单

也就是说，运行时虽然不一定直接读取每个组件的原始 config.json，但它消费的整个世界观，已经被协议预先塑形了。

这和“组件自己想怎么写就怎么写，运行时临场适配”是完全不同的两种系统。前者的好处是：

版本清单更稳定
产物可追踪
页面问题更容易回溯到协议或构建阶段
回滚和灰度不会沦为一次危险的全量重部署

从系统设计角度说，协议在这里起到的是“给运行时降维”的作用。它不需要理解所有实现细节，只需要消费被规范化后的结果。

七、本地预览之所以能成立，也是因为协议足够统一

一个常被忽略的事实是：本地开发环境其实也是协议消费者。

如果没有统一协议，本地预览通常会变成一堆临时脚本：这个组件手工喂一份 mock 数据，那个组件再单独配一个 demo 页面，等到接入后台或 SSR 时又发现行为不一致。

但在这个项目里，components/README.md 已经把约束写得很明确：组件要能被正确读取，至少要遵从目录结构，并提供 index.ts、render.tsx、config.json。这意味着本地预览、构建上传、后台接入，依赖的是同一套组件描述方式，而不是三套互相兼容的临时方案。

这个统一性会带来两个直接收益：

开发阶段和生产阶段的认知模型一致：组件在本地怎么被识别，进入后台和构建流程时仍然怎么被识别。
排错路径更短：如果组件没有被正确读取，优先看协议和结构，而不是去猜是不是某个环境脚本失效了。

对平台型系统来说，这种“一份定义，多处复用”的收益，比单个功能点上的灵活性更重要。

八、协议驱动真正难的，不是定义字段，而是守住演进边界

写一份 configSchema.json 并不难，难的是让它在系统演进中一直保持可信。

协议驱动最容易失败的方式有三种：

8.1 把协议当成注释，而不是约束

如果 schema 只是“写着看看”，构建器不校验、编辑器不严格消费、后台还能随便补字段，那协议很快就会失去权威性。最终团队又会回到“以实现为准”的老路。

这个项目里比较可贵的一点，是构建链路已经开始把协议当成硬约束，例如 fetch 和 fetchArgs 的一致性检查。这种做法越多，协议的可信度越高。

8.2 把所有变化都塞进协议

协议应该承载系统间共享的事实，而不是吞掉所有业务细节。

比如 key、version、category、config、fetchArgs 这些是天然跨系统的；但某些高度局部、强实现相关的逻辑，如果也强行塞进协议，最后只会得到一个臃肿且难以维护的配置中心。

一个实用判断标准是：如果某个字段只有一个系统关心，而且只和实现细节相关，那它不一定适合进共享协议。

8.3 协议升级没有兼容策略

页面平台不是一次性系统，协议也不可能永远不变。真正的难点在于升级时如何做到：

新组件可以使用新字段
旧组件不需要立即迁移
编辑器和构建器能识别不同阶段的协议形态
发布系统不会因为协议升级而批量破坏存量页面

这也是为什么文章开头强调 version 很重要。它不只是组件版本号，同时也是系统组织兼容性的抓手。没有版本意识的协议，最终很难支撑长期演进。

九、回头看，协议驱动的本质是把“共识”从人脑里拿出来

这篇文章如果只停留在“配置很重要”，其实没有太大意义。真正值得总结的是：协议驱动解决的，不是配置文件问题，而是复杂系统里的共识分发问题。

后台、编辑器、构建器、SSR、本地预览，本来都需要理解“组件是什么”。如果这个理解靠口头同步、靠文档、靠经验，系统规模一大就必然分叉。协议做的事，是把这份共识外化成一份结构化、可校验、可消费、可演进的契约。

所以它不是代码的退而求其次，恰恰相反，它是一种更高层的系统设计。

对于多站点页面平台来说，真正重要的不是“有没有很多组件”，而是这些组件是否先被描述成了统一资产；不是“编辑器能不能拖拽”，而是编辑器是否只需要理解协议；也不是“SSR 能不能 render”，而是构建和运行时是否建立在同一套契约之上。

换句话说，协议驱动并不是用配置代替代码，而是用协议把多个系统拉回到同一个现实里。

这也是 MultipleSite 这套系统最值得复用的地方。

0 条评论

发表评论