12.7 阶段 6 Node BFF 与 SSR
本页目录
一、阶段定位
本阶段把前端从「只在浏览器跑」延伸到「能在 Node 服务端跑一段」:BFF(Backend For Frontend)在 Node 层聚合后端接口、做鉴权与裁剪;SSR(服务端渲染)把组件在服务器渲染成 HTML 再下发,解决首屏与 SEO。基线:Node 20、Next.js 14 App Router 或 Nuxt 3、Vite SSR。很多人听过 SSR 但说不清「水合(hydration)」是什么、为什么会闪烁、为什么直出 HTML 后还要在浏览器再跑一遍 JS。
不掌握本阶段会在后面具体卡在哪:
- 把 BFF 当普通后端写,不知道它的职责是「为前端裁剪数据、聚合多个后端接口」,而不是重新写一套业务。
- SSR 页面首屏能看到,但水合后交互失效,报
Hydration failed,不知道服务端渲染的 HTML 与客户端首次渲染不一致。 - 把密钥放在前端环境变量里,SSR 时本该用服务端密钥却打进了客户端 bundle。
- 不会区分 SSR/SSG/ISR 三种渲染模式,什么页面都上 SSR,服务器压力大。
判断卡住的标志:让你解释「用户请求一个 SSR 页面,到浏览器可交互,中间发生了什么」,你只能说「服务器返回 HTML」,说不清楚数据预取、水合、id 不一致这类问题。出现任一现象,先把本阶段六个模块过一遍再进 阶段 7 性能、安全与可访问性。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能写一个 Express/Hono 接口聚合两个后端 | BFF 返回裁剪后的前端数据 |
| 能解释 CSR/SSR/SSG/ISR 的差别与取舍 | 给具体页面选渲染模式 |
| 能用 Next.js App Router 或 Nuxt 写一个 SSR 页面 | 查看源码能看到直出 HTML |
| 能解释水合过程与 Hydration mismatch 原因 | 修掉一个 mismatch 警告 |
| 能区分客户端与服务端环境变量 | 服务端密钥不进 bundle |
| 能处理 SSR 下的请求与缓存 | 同构代码不访问 window/document |
建议学时:
- 全职:2.5 周,约 45 小时。Node HTTP/Express 基础 8 小时、BFF 模式 8 小时、SSR 原理与水合 10 小时、Next/Nuxt 实战 12 小时、渲染模式取舍 4 小时、练习 3 小时。
- 在职:5 周,约 50 小时。
三、先修自检
| 先修项 | 合格标准 | 不合格时怎么办 |
|---|---|---|
| 阶段 4 产出 | 能封装请求层、TanStack Query | 回到 12.5 |
| Node 基础 | 能跑 Node 脚本、了解 ESM | 回到 12.1 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| Node Web 服务 | Express/Hono、路由、中间件、请求响应 | 会用 | 纯文本章节:Node.js 后端(题库 04 后端语言与运行时 Node 章节) |
| BFF 模式 | 接口聚合、数据裁剪、鉴权、缓存 | 能讲清原理 | 03.7 SSR、SSG 与全栈前端 |
| 渲染模式 | CSR、SSR、SSG、ISR 的取舍 | 能讲清原理 | 03.7 SSR、SSG 与全栈前端 |
| 水合 | hydration、mismatch、服务端/客户端一致 | 能讲清原理 | 03.7 SSR、SSG 与全栈前端 |
| 同构注意点 | 不访问 window/document、环境变量区分 | 会用 | 03.7 SSR、SSG 与全栈前端 |
| 框架 | Next.js 14 App Router / Nuxt 3 | 会用 | 03.7 SSR、SSG 与全栈前端 |
五、分模块精讲
5.1 Node Web 服务基础
为什么需要它:BFF 就是跑在 Node 上的一个 HTTP 服务,要先会写路由、中间件、读请求。
核心机制:
- 选 Hono(轻量、快、TypeScript 友好)或 Express(生态大);本路径示例用 Hono,Express 概念相通。
- 路由:
app.get('/users', c => c.json({ ... }));中间件:日志、CORS、鉴权。 - 请求生命周期:拿到请求 → 中间件链 → 路由处理 → 返回响应 JSON。
最小可运行示例:
// server.ts(Hono + Node)
import { Hono } from 'hono'
import { logger } from 'hono/logger'
const app = new Hono()
app.use('*', logger())
app.get('/api/hello', c => c.json({ message: 'hi' }))
export default app
// 用 @hono/node-server 起:
// import { serve } from '@hono/node-server'
// serve(app)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 跨域被拦 | 没配 CORS | 用 hono/cors 中间件 |
| 端口被占 | 上次进程没退 | 换端口或杀进程 |
面试考法:问 BFF 与后端服务的区别。答到:BFF 为前端裁剪聚合、不持有核心业务规则、可按端拆分;后端服务是领域能力的权威来源。
5.2 BFF 聚合与裁剪
为什么需要它:前端一个页面要调后端三个接口,串行瀑布加载慢;BFF 在服务端并行聚合成一个接口返回,前端只发一次请求。
核心机制:
- 并行请求多个后端:
Promise.all([fetchA, fetchB])。 - 裁剪字段:后端返回 20 个字段,前端只用 3 个,BFF 直接返回需要的,减小体积。
- 鉴权:BFF 校验登录态后用服务端凭证调内部后端,前端不直接接触内部地址。
最小可运行示例:
app.get('/api/pages/home', async c => {
const [user, banners, notices] = await Promise.all([
fetchInternal('/users/me'),
fetchInternal('/banners'),
fetchInternal('/notices')
])
return c.json({
userName: user.name,
banners: banners.map(b => ({ id: b.id, url: b.url })),
notice: notices[0]?.title ?? ''
})
})
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| BFF 慢 | 串行请求后端 | 改 Promise.all 并行 |
| 后端字段改了 BFF 崩 | 没做字段防御 | 加默认值与 schema 校验 |
5.3 渲染模式:CSR / SSR / SSG / ISR
为什么需要它:不是所有页面都要 SSR,选错模式要么 SEO 差、要么服务器压力大。
核心机制:
- CSR(客户端渲染):浏览器拿到空 HTML + JS bundle,下载执行后渲染;首屏慢、SEO 弱,但交互快、服务器轻。适合登录后中后台。
- SSR(服务端渲染):每个请求服务器把组件渲染成 HTML 再下发;首屏快、SEO 好,但服务器要算、要承担并发。适合营销页、内容页。
- SSG(静态生成):构建时把页面渲染成静态 HTML;首屏极快、可 CDN 缓存,适合博客文档、不常变的内容。
- ISR(增量静态再生):静态生成后按时间在后台重新生成,兼顾快与新鲜。
最小可运行示例(Next.js App Router 约定):
// app/blog/page.tsx(Next.js App Router 默认 SSR/动态)
export default async function BlogPage() {
const posts = await fetch('https://api.example.com/posts', { cache: 'no-store' })
const data = await posts.json()
return <ul>{data.map((p: any) => <li key={p.id}>{p.title}</li>)}</ul>
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 什么页面都 SSR | 没区分场景 | 中后台用 CSR,内容用 SSR/SSG |
| SSG 内容不更新 | 构建时写死 | 用 ISR 或重新部署 |
面试考法:给一个页面选模式。要能说出:营销首页 SSR/ISR、博客 SSG、登录后中后台 CSR。
5.4 水合与 Hydration Mismatch
为什么需要它:SSR 直出 HTML 后,浏览器要「接管」这棵 HTML 并绑定事件,这就是水合;服务端与客户端首次渲染不一致会报警告甚至交互失效。
核心机制:
- 直出 HTML 是服务端渲染的快照;下载 JS 后客户端用同一份组件再渲染一次(虚拟 DOM),与现有 HTML 对比绑定事件,称为水合。
- mismatch 常见原因:服务端与客户端数据不同(时区、随机数、
Date.now())、浏览器特有 API(window)在渲染期访问、条件分支不一致。 - 修法:渲染期不访问
window;随机/时间在useEffect里取;用suppressHydrationWarning标记可控差异(如时间格式化)。
最小可运行示例:
import { useEffect, useState } from 'react'
export function Time() {
const [now, setNow] = useState<string>('')
// 不在渲染期读 Date.now(),避免服务端与客户端不一致
useEffect(() => { setNow(new Date().toLocaleTimeString()) }, [])
return <p suppressHydrationWarning>{now || '…'}</p>
}
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| Hydration failed | 渲染期访问 window | 移到 useEffect |
| 文本不一致 | 服务端与客户端时区不同 | 固定时区或 suppressHydrationWarning |
面试考法:问水合是什么。答到:服务端直出 HTML 后,浏览器下载 JS 重新渲染虚拟 DOM 并与 HTML 绑定事件的过程;不一致会导致警告或交互失效。
5.5 环境变量与服务端密钥
为什么需要它:SSR 代码同时跑在 Node 与浏览器,密钥绝不能进浏览器 bundle。
核心机制:
- Next.js:
NEXT_PUBLIC_前缀进客户端;无前缀只在服务端可用。 - Nuxt:运行时 config 区分
private(服务端)与public(客户端)。 - 同构代码里要用客户端才有值的变量,判断
import.meta.env.SSR或typeof window。
最小可运行示例:
# .env(服务端,不进 bundle)
DATABASE_URL=postgres://...
INTERNAL_API_KEY=secret
# .env 里以 NEXT_PUBLIC_ 开头的才进客户端
NEXT_PUBLIC_API_BASE=https://api.example.com
// 只在服务端读
const key = process.env.INTERNAL_API_KEY
// 客户端读公开配置
const base = process.env.NEXT_PUBLIC_API_BASE
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 密钥出现在 bundle | 加了公开前缀 | 去掉前缀,只用服务端 |
| 服务端代码访问 window 报错 | 同构代码没判断 | 加 typeof window 判断 |
5.6 数据预取与缓存
为什么需要它:SSR 要在返回 HTML 前拿到数据,不能组件挂载后再请求,否则首屏是空骨架。
核心机制:
- Next.js App Router:async 组件直接
await数据,渲染完成后再返回 HTML。 - Nuxt:
useFetch/useAsyncData在服务端预取,序列化后注水(dehydrate)到客户端,避免水合时重复请求。 - 缓存:Next 的
fetch默认缓存,按next: { revalidate: 60 }设 ISR;不缓存用cache: 'no-store'。
最小可运行示例:
// Nuxt
const { data } = await useFetch('/api/users', { baseURL: import.meta.env.VITE_API_BASE })
// data 在服务端就取好,客户端水合时直接复用
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 首屏先空后填 | 客户端挂载后才请求 | 改服务端预取 |
| 重复请求 | 没注水数据 | 用框架的 useFetch/useAsyncData |
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 写一个 Hono 接口 | 返回 JSON | curl 能拿到 | 1.5 小时 |
| BFF 聚合 | 并行调两个后端返回裁剪数据 | 前端一次请求拿到 | 2 小时 |
| 起一个 Next/Nuxt 页面 | 查看源码有直出 HTML | 查看页面源代码非空 | 2 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 修一个 Hydration mismatch | 故意在渲染期读 window,再修 | 警告消失 | 1.5 小时 |
| 把 CSR 列表改成 SSR 预取 | async 组件 await 数据 | 首屏直接有内容 | 2 小时 |
| 区分环境变量 | 服务端 key 不进 bundle | 搜 bundle 找不到 | 1 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 为一个内容站选渲染模式 | 首页/博客/登录后台分别选 | 能说取舍 | 1 小时 |
| 设计一个 BFF 聚合接口 | 含鉴权、并行、裁剪、错误兜底 | 单接口返回页面数据 | 3 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| Hydration failed | 渲染期访问 window/数据不一致 | 看控制台组件栈 | 移到 useEffect、固定数据 |
| 首屏先空后填 | 客户端挂载才请求 | 看 Network 时序 | 改服务端预取 |
| 重复请求 | 没注水 | 看 Network 是否两次 | 用 useFetch/async 组件 |
| 密钥进了 bundle | 公开前缀 | 搜 bundle | 去前缀 |
| 服务端代码报 window undefined | 同构没判断 | 看调用栈 | typeof window 判断 |
| SSG 不更新 | 构建写死 | 看部署 | ISR 或重新部署 |
| SSR 并发压垮 | 什么都 SSR | 看 CPU/内存 | 中后台改 CSR、加缓存 |
| 跨域被拦 | BFF 没 CORS | 看响应头 | 加 CORS 中间件 |
八、出口条件
全部勾选后进入 阶段 7 性能、安全与可访问性。
- [ ] 能写一个 Hono/Express 接口并并行聚合多个后端
- [ ] 能给具体页面选 CSR/SSR/SSG/ISR 并说出取舍
- [ ] 能解释水合过程并修掉一个 mismatch
- [ ] 能区分服务端与客户端环境变量,密钥不进 bundle
- [ ] 能用 Next App Router 或 Nuxt 做数据预取,首屏直出内容
自测题:
- CSR 与 SSR 首屏有什么差别?
- 要点:CSR 先下 JS 再渲染,SSR 直接返回 HTML。
- 什么是水合?为什么会 mismatch?
- 要点:浏览器接管 HTML 绑定事件;服务端与客户端首次渲染不一致。
- BFF 的职责是什么?
- 要点:聚合、裁剪、鉴权,不持有核心业务规则。
- 服务端密钥怎么避免进客户端 bundle?
- 要点:不加公开前缀,只在 Node 环境读。
- SSG 与 ISR 的区别?
- 要点:SSG 构建时生成,ISR 后台按时间再生。
- 为什么中后台不建议上 SSR?
- 要点:登录后内容无需 SEO,SSR 增加服务器压力无收益。