多渲染方式统一接入：一套 BFF 页面架构的设计思路

做 BFF 页面系统时，我们很快遇到一个问题：不同页面对渲染方式的要求并不一样。

有的页面要 SEO，有的页面交互很重，有的页面首屏性能优先，有的页面则更在意稳定性。更麻烦的是，SSR 这条链路一旦在服务端出错，用户可能连一个可用页面都拿不到。接口超时、数据格式异常、模块加载失败、renderToString 抛错，都可能把一次页面请求打断。

如果每类页面各自接一套渲染流程，短期看很快，长期看会变成一堆分散的入口、模板和异常处理逻辑。最后团队不是在维护页面，而是在维护各种历史接入方式。

这篇文章记录的是我们对 BFF 页面架构的一次整理：统一的是页面接入方式，不是页面渲染方式。页面可以选择 SSR、CSR、静态生成或混合模式，但它们要以同一种方式声明、注册、渲染和降级。

问题不是 SSR 还是 CSR

SSR 和 CSR 的差异并不难理解。

SSR 首屏快，对 SEO 友好，内容能更早出现在 HTML 里。但它把数据获取、模板执行、组件渲染都放进了服务端请求链路，任何一个环节出错，都可能影响整页输出。

CSR 对服务端依赖更弱，稳定性通常更好，但首屏和 SEO 要吃亏。对于强交互页面，这不是问题；对于营销页、落地页、公开详情页，就会比较明显。

真实项目里更常见的情况是：团队不可能只选一种模式。

营销页需要 SSR 或静态生成。
后台页、配置页更适合 CSR。
一些页面希望 SSR 优先，但失败时能回退到 CSR。
还有一些页面只需要复用统一路由和模板，不想关心底层渲染流程。

所以这里真正要解决的不是“选 SSR 还是 CSR”，而是：页面如何用统一方式接入，平台如何根据页面声明选择渲染流程，并在失败时继续交付一个可用页面。

为什么放在 BFF 层

BFF 刚好站在用户请求和业务服务之间。它知道当前请求的域名、路径、语言、设备信息，也能串联数据获取、页面模板、错误处理和日志上报。

如果把多渲染接入放在纯前端层，页面已经到浏览器了，SSR 的成功失败无从谈起。如果放在更前面的网关层，网关又不应该理解 React 组件、页面模板和业务渲染上下文。

BFF 层比较适合做这件事，是因为它能同时处理几类信息：

请求上下文：域名、路径、语言、AB 实验、设备类型。
页面配置：页面类型、路由规则、渲染模板、降级策略。
渲染运行时：服务端入口加载、数据获取、HTML slot 注入。
失败处理：SSR 异常捕获、日志打点、CSR fallback 输出。

这不是说所有项目都应该上 BFF 页面平台。它适合页面数量多、渲染诉求不一致、又希望统一接入规范的团队。项目很小、页面类型单一、没有 SEO 或服务端渲染要求时，这套东西会显得偏重。

页面如何统一接入

统一接入的关键，是让页面先声明自己，而不是让开发者到处改入口文件。

一个页面可以用类似这样的 config.toml 描述：

[page]
type = "react-ssr-fallback-csr"
 
[router]
domain = "<%=SERVER_OFFICIAL_DOMAIN%>"
path = ["/cart"]
 
[render]
fallback = "csr"
timeout = 3000

这份配置表达了几件事：

type 决定页面使用哪一类模板。
router 决定页面挂在哪个域名和路径下。
fallback 决定 SSR 失败后如何继续交付。
timeout 给服务端渲染链路一个明确的上限。

页面接入方只需要维护页面配置和业务入口。路由注册、模板选择、客户端入口、服务端入口、异常兜底都由平台根据配置补齐。

请求进来以后，流程大概是这样：

这里的重点不是流程图有多复杂，而是成功路径和失败路径都被写进了平台流程里。失败不是散落在业务代码里的 try/catch，而是页面系统的一部分。

模板承接不同渲染方式

页面配置里的 type 最终会落到模板选择上。

模板负责描述一类页面怎么被交付，比如：

react-csr：只输出客户端入口和基础 HTML。
react-ssr：服务端先渲染 HTML，客户端再 hydrate。
react-ssr-fallback-csr：SSR 优先，失败后返回 CSR Shell。
static：构建期生成静态内容。

模板化的价值，不是单纯“支持更多模式”，而是把渲染流程从业务页面里拿出来。业务页面不需要重复关心怎么创建客户端入口、怎么加载服务端入口、HTML slot 怎么注入、SSR 失败怎么处理。

当团队要调整某一类页面的渲染策略时，改的是模板能力，而不是把几十个页面逐个翻出来重写。

这也是为什么“统一接入”和“统一渲染”要分开看。统一渲染会逼所有页面走同一种模式，最后总会有人不合适；统一接入则是让不同模式挂在同一套平台协议下面。

SSR 失败后怎么降级到 CSR

这套架构里最值得单独展开的，是 SSR 失败自动降级 CSR。

它解决的不是“让错误消失”，而是把错误变成可处理的状态。SSR 失败以后，用户不一定拿到最理想的首屏 HTML，但至少还能拿到一个可运行的 CSR 页面。

常见的 SSR 失败来源包括：

服务端接口超时或返回异常数据。
页面模块加载失败。
React 渲染过程抛错。
依赖了只在浏览器存在的 API，比如 window 或 localStorage。
模板里的 slot 注入、序列化或数据转换出错。

平台层的处理逻辑可以简化成这样：

async function renderPage(ctx: RenderContext): Promise<Response> {
  const page = await matchPage(ctx);
  const template = await resolveTemplate(page.type);
 
  if (!template.ssr) {
    return template.renderCSR(ctx);
  }
 
  try {
    return await withTimeout(
      template.renderSSR(ctx),
      page.render.timeout ?? 3000,
    );
  } catch (error) {
    reportSSRFailure(error, {
      pageId: page.id,
      url: ctx.url,
      fallback: page.render.fallback,
    });
 
    if (page.render.fallback === 'csr') {
      return template.renderCSR(ctx);
    }
 
    throw error;
  }
}

这段逻辑有几个关键点。

第一，SSR 失败必须被记录。降级不是把错误吞掉，否则线上会变成“用户没报错，系统一直在偷偷降级”。日志、打点、告警都应该在这里做。

第二，降级要受页面配置控制。不是所有页面都适合 CSR fallback。强 SEO 页面如果降级成空壳，搜索引擎看到的内容就没了；而一些登录后页面、配置页、活动页，CSR fallback 可能是更合理的取舍。

第三，CSR Shell 也要是正式产物。它不是临时错误页，而是一份可以让浏览器重新拉数据、重新渲染业务页面的 HTML。

整个过程可以用一张时序图看：

这条 fallback 路径的价值，是把“失败后怎么办”从临时补丁变成平台行为。页面不用各自发明错误恢复逻辑，平台也能统一观测 SSR 的失败率和降级情况。

三层分工

把实现拆开看，这套系统大致分成三层。

页面层负责描述页面本身：页面配置、路由信息、页面入口、页面选择哪种模板。它回答的是“这个页面是谁，想怎么被交付”。

运行层负责处理请求和渲染：匹配路由、加载模板、执行 SSR、输出 CSR Shell、处理降级和错误上报。它回答的是“系统如何把页面送到用户面前”。

业务能力层负责提供 API、共享组件、业务 hooks 和通用工具。它回答的是“页面渲染时需要哪些业务能力支持”。

拆成这三层以后，页面就不再是一段孤立代码，而是平台里的一个标准单元。业务页面只关心业务表达，运行层接住渲染和失败恢复，底层能力则保持复用。

这套方案适合什么场景

这套架构不是越早上越好。它适合这些场景：

页面数量多，并且不同页面对 SSR、CSR、静态生成有不同诉求。
团队希望统一路由、模板、入口和页面接入规范。
业务同时关注 SEO、首屏体验和线上稳定性。
SSR 失败不能直接影响用户访问，需要正式的降级策略。
多个页面团队共用一套页面平台，需要把底层渲染能力收敛起来。

不太适合的场景也很明确：项目规模小、页面类型单一、没有 SEO 要求、也不需要服务端渲染。这时直接用普通 CSR 或框架默认能力会更轻。

架构是否合理，不取决于它看起来有多完整，而取决于它有没有匹配问题规模。为三个页面搭一套平台，大概率是过度设计；为几十个页面统一入口、模板和降级策略，就有现实收益。

小结

多渲染方式统一接入，核心不是给页面多加几种渲染手段，而是把页面接入方式、模板选择和失败恢复收敛到同一套 BFF 页面平台里。

这样做之后，业务页面不用重复搭建入口和渲染流程；平台可以统一处理路由、模板、SSR 执行、CSR fallback 和异常观测。不同渲染模式仍然可以并存，但它们不再各自长出一套接入方式。

最后真正省下来的，不只是几段入口代码，而是后续页面增长时的维护成本。

2026-04-24

0 条评论

发表评论