企业官网建设流程全解析

1. 项目缘起：为什么偏偏是 Node BFF 加 Vue3 SSR

很多人问我，前端项目做到什么程度才需要折腾服务端渲染？我给的答案很简单：当你的页面内容需要被搜索引擎抓到、当首屏加载速度开始被用户吐槽、当你发现自己在前端代码里偷偷拼接口数据拼到怀疑人生的时候，就该考虑架构升级了。我这次做这个项目，起因就是接手了一个内容型后台系统，首屏白屏时间接近三秒，SEO 完全没戏，而且前端要对接的数据源多达四套，鉴权逻辑还各自为政。

Vue3 作为当前主流的前端框架，配合 SSR 之后既保留了组件化开发体验，又能让首屏 HTML 直接带出完整内容。而 BFF 层，也就是 Backend For Frontend，承担了前端与后端所有数据源之间的缓冲和聚合职责。我这次把 Node BFF 和 Vue3 SSR 组合在一起，等于同时解决了前端数据聚合、接口鉴权、服务端渲染三层问题。

公开源码是我一贯的习惯，因为这个项目踩坑实在太多，多到我觉得不分享出去有点浪费。从 Node 环境搭建到 Vue3 的 SSR 渲染链路打通，从 BFF 层的接口路由设计到部署时的资源路径处理，每一步都有值得记录的细节。这篇博客我尽量按照实操顺序来写，把核心代码、踩坑记录、排查思路全部放出来，希望能给正在搞 Vue3 SSR 或 Node BFF 的朋友省几天时间。

2. 整体架构设计：BFF 层到底解决了什么问题

2.1 BFF 层的职责边界

BFF 层不是一个新概念，但很多人对它存在误解。它不是简单的反向代理，也不是一个纯粹的 Node 中间件，而是专门为前端服务的后端层，聚焦于把多个后端服务的数据组装成前端最需要的结构。在这个项目里，我其实需要同时对接用户服务、内容服务、权限服务三个后端接口，如果前端直接去调用这三个服务，会遇到几个问题。

请求数量太多，一个页面可能要发五六次请求才能拿到完整数据，客户端体验很差；后端返回的数据结构不统一，有的服务返回的是嵌套结构，有的直接返回字符串；另外，鉴权逻辑如果放在前端，很容易被绕过。BFF 层出现之后，前端只需要请求一次，BFF 收到请求后并发调取多个后端服务，把数据结构化重组之后再返回给前端。对于 Vue3 SSR 来说，BFF 层还有另外一个重要作用——让服务端渲染时的数据获取变成一次可靠的内部调用，不走跨域不走代理，减少了非常多的网络开销。

2.2 Node 作为 BFF 的语言优势

为什么选 Node 而不是 Java 或 Go？对前端团队来说，Node 最大的优势是语言同构。前端同学不需要再学一门新语言，JavaScript 的 async/await 处理并发请求非常顺手，而且 npm 生态里现成的库特别多。我在做这个项目的时候，整个 BFF 层用了不到五百行代码，如果换 Java 写，光配置类可能就得写两百行。

Node 在处理 IO 密集型任务上的表现也很适合 BFF 场景。BFF 做的事情主要是转发请求和聚合数据，算力消耗不大，反而是大量 IO 等待，真实需求的正是这类轻量级高并发的服务。再加上 Node 18 以后原生支持 fetch，连请求库都不需要额外装了，后面的调用逻辑直接内置函数就能解决。

2.3 项目目录结构与关键依赖

这个项目的技术栈比较克制，核心就三块：Vue3 负责页面和组件，Node 原生 HTTP 模块加自定义路由来搭建 BFF 层，Vite 负责客户端构建和服务端代码打包。我没有引入 Koa 或 Express，因为在 BFF 这个场景下，原生的 HTTP 模块搭配几个小工具函数就够用了，少一层依赖就少一份踩坑风险。

project-root/ ├── bff/ # Node BFF 层 │ ├── server.js # BFF 入口文件 │ ├── router.js # 路由注册器 │ ├── handlers/ # 接口处理器目录 │ │ ├── user.js # 用户信息聚合 │ │ └── content.js # 内容列表聚合 │ └── utils/ │ ├── http.js # HTTP 请求封装 │ └── cache.js # 内存缓存简单实现 ├── client/ # Vue3 前端部分 │ ├── index.html │ └── src/ │ ├── entry-client.js # 客户端入口 │ ├── entry-server.js # 服务端入口 │ ├── App.vue │ └── views/ │ ├── Home.vue │ └── Detail.vue ├── vite.config.js # Vite 配置 ├── package.json └── README.md

我建议你复制这套结构时，务必把 BFF 层和前端目录分开存放，不要混在一个 src 里面。否则构建工具会把 BFF 的代码也打进前端包里，后期维护会非常痛苦。

3. 环境准备：Node 安装、版本切换与镜像配置

3.1 安装 Node 与版本管理器的选择

做 Vue3 SSR 项目，Node 版本不能太低。Vite 5 要求 Node 18 以上，Vue3 官方的 SSR 示例也要求 Node 16 起步，而如果需要用 Node 18 自带的 fetch，那可以直接锁定 Node 18 或更新版本。我在项目里用的 Node 22.19，稳定性没问题，而且对现代 JavaScript 语法的支持非常完整。

如果机器上还没有 Node，最省事的方式是先装 NVM，而不是直接去官网下载安装包。我在微博上不止一次看到有人说，装了 Node 然后又因为权限问题想卸载换版本，最后把系统搞得一团糟。用 NVM 可以随时切换 Node 版本，项目里甚至可以配置.nvmrc文件来固定版本号。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装完成后重开终端 nvm install 22.19.0 nvm use 22.19.0 nvm alias default 22.19.0

Windows 用户建议直接去 GitHub 下载 NVM for Windows 的安装包，安装后在 PowerShell 里执行nvm install 22.19.0同样好用。如果遇到 PowerShell 提示“禁止运行脚本”的报错，后面我会有专门的排查章节来聊。

3.2 国内镜像源配置是省时间的第一步

Node 装好了，第一件事不是写代码，而是配置 npm 镜像源。默认源在创建项目拉取依赖的时候速度极慢，挂载代理也可能带来不确定的安全风险，所以直接用国内镜像是最稳的做法。

npm config set registry https://registry.npmmirror.com # 验证设置生效 npm config get registry

另外，NVM 的下载源也可以走镜像，这是一个很容易被遗漏的点。如果你用nvm install 22.19.0下载时一直卡住或者超时，可以设置 NVM 的镜像地址：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

TCP 连接数上去了，区别非常明显。在这个项目里，需要安装的依赖包括 Vite、Vue3、@vitejs/plugin-vue 等，如果用默认源，光是下载和安装就可能花费十几分钟，配好镜像后通常三分钟内就能搞定。

4. Vue3 SSR 核心链路：从客户端入口到服务端渲染

4.1 双入口设计的基本逻辑

Vue3 SSR 项目需要两个入口文件，这是很多新手第一次接触时容易混淆的地方。客户端入口entry-client.js负责在浏览器里创建应用实例并挂载到 DOM 上；服务端入口entry-server.js则负责在每次请求到来时创建应用实例，将组件渲染成 HTML 字符串返回给客户端。

我画个简单的对应关系来帮助你理解：客户端入口运行一万次，因为每个浏览器打开页面都会跑一次；服务端入口则运行无数次，因为每次请求都会触发它执行一次。但这两个入口跑的是同一个App.vue，只是挂载方式不同，这就是同构应用的核心——创建工厂函数。每次请求都不能复用原来的应用实例，否则就会出现状态污染，用户 A 的数据串到用户 B 页面上，这是 SSR 最经典的一个坑。

4.2 Vite 插件为 SSR 带来的构建简化

在 Vite 之前，做 Vue SSR 需要额外学习一套 webpack 配置，服务端和客户端的构建配置完全不通用。Vite 出现后，这种情况得到了极大改善，它的插件机制天然支持 SSR 开发模式。在vite.config.js里我们需要做几件事：配置 Vue 插件，设置别名让@指向src目录，同时为 SSR 构建设置特定的输出格式。

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': '/src' } }, build: { rollupOptions: { output: { format: 'es' } } } })

开发模式下，Vite 会启用模块热更新，我改一个组件的代码，浏览器页面立刻刷新，这种开发体验是传统 SSR 框架无法比拟的。生产模式下，Vite 会把客户端代码打包成静态文件，服务端代码打包成 CommonJS 模块供 Node 调用。

4.3 服务端渲染的完整流程拆解

服务端渲染的本质是把 Vue 组件渲染成 HTML 字符串，再塞进一个完整的页面模板中返回。我在 BFF 层接到的每个请求都会走一遍这个流程：解析路由、判断当前路径对应的组件、在组件中触发数据预取（也就是请求 BFF 接口获取数据）、用这些数据生成App.vue实例、通过renderToString生成 HTML。但客户端同样需要这些数据，否则就会出现水合失败的问题。

为了解决这个问题，我引入了pinia状态管理，通过pinia将服务端预取的数据序列化为 JSON，嵌到 HTML 中的<script>标签里，客户端应用启动后先读取这段数据注入到状态管理中，再执行hydrate挂载。整个过程说起来简单，但中间需要处理好很多细节，比如组件的异步数据预取要放到onServerPrefetch钩子中，而不是onMounted，因为onMounted在服务端根本不会执行。

// entry-server.js import { createApp } from './main' import { renderToString } from '@vue/server-renderer' import { createPinia } from 'pinia' export async function render(url, manifest) { const { app, router, pinia } = createApp() router.push(url) await router.isReady() const ctx = { pinia } const html = await renderToString(app, ctx) return { html, state: JSON.stringify(pinia.state.value) } }

服务端渲染的另一个关键点是资源注入。客户端构建后会生成带哈希的文件名，比如index-D4F2K92.js，服务端怎么能知道当前该引用哪个 JS 文件呢？我的做法是在构建结束后，让 Vite 生成一份ssr-manifest.json文件，里面记录了组件和模块的映射关系，服务端根据当前渲染的组件找到对应的预加载资源，生成完整的<link rel="preload">和<script src="...">标签。

5. BFF 层实现：数据聚合、接口路由与缓存策略

5.1 BFF 层的基本路由分发实现

BFF 层虽然没上框架，但我还是把路由逻辑单独抽了一个文件出来，方便后续扩展。核心思路非常简单：定义一个路由表，用路径做匹配，命中后执行对应的处理器函数。如果你在处理过程中需要支持动态路径参数，加一层正则匹配就好了。

// router.js const routes = [ { path: '/api/user/profile', handler: require('./handlers/user').profile }, { path: '/api/content/list', handler: require('./handlers/content').list }, { path: '/api/content/detail/:id', handler: require('./handlers/content').detail } ] function matchRoute(pathname) { for (const route of routes) { const keys = [] const regex = new RegExp( '^' + route.path.replace(/\/:([^/]+)/g, (_, key) => { keys.push(key) return '/([^/]+)' }) + '$' ) const match = pathname.match(regex) if (match) { const params = {} keys.forEach((key, index) => { params[key] = match[index + 1] }) return { handler: route.handler, params } } } return null }

这里要注意一点，写/api/content/detail/:id这种路径时，正则匹配会把/当成普通字符处理，所以捕获组用了([^/]+)，这样即使 id 里带了斜杠也能正确处理。

5.2 处理器怎么做到并发聚合

我觉得处理器才是 BFF 层最核心的代码。以用户详情页为例，这个页面需要展示用户基本信息、用户最近发布的内容、用户的权限标签三个部分，这三个数据分别存在于两个不同的后端服务中。如果前端自己调，至少要发三次请求；通过 BFF 聚合之后，前端只请求一次，拿到一个定义良好的 JSON 结构。

// handler/user.js const { fetchJson } = require('../utils/http') async function profile(req, res, params) { const userId = params.id || req.headers['x-user-id'] const [baseInfo, recentPosts, roleTags] = await Promise.all([ fetchJson(`http://user-service/api/users/${userId}`), fetchJson(`http://content-service/api/users/${userId}/posts?limit=5`), fetchJson(`http://auth-service/api/users/${userId}/roles`) ]) res.setHeader('Content-Type', 'application/json') res.end(JSON.stringify({ code: 0, data: { ...baseInfo, recentPosts: recentPosts.data, roles: roleTags.data } })) }

这个并发策略非常关键。我之前看到有人用await依次调用三个接口，先查完用户基本信息再查内容列表，查完内容列表再查权限标签，这三个请求的时间变成了串行相加。改成Promise.all之后，总耗时取决于最慢的那个请求，前端页面渲染速度直接提升了接近三倍。

5.3 给 BFF 层加上内存缓存和超时控制

BFF 层虽然已经把多个请求合并成了一个，但如果每个请求都传到后端服务，后端压力还是很大。我的做法是在 BFF 层增加一个简单的内存缓存，针对内容列表这类热点数据，缓存时间设置为 30 秒。用户的请求进来时，先查缓存，命中就直接返回，不命中才穿透到后端服务。

同时，我还要给 BFF 层加超时保护。后端服务如果挂掉了，BFF 层的请求就会一直挂着，前端的请求也会一直转圈，用户看到的就是一个无限 loading 的页面。我给每个 fetch 请求设置了 3 秒超时，超时后返回一个统一的降级数据结构，前端拿到之后可以展示兜底 UI，而不是白屏。

// utils/http.js const timeoutMs = 3000 async function fetchJson(url, options = {}) { const controller = new AbortController() const timer = setTimeout(() => controller.abort(), timeoutMs) try { const res = await fetch(url, { ...options, signal: controller.signal, headers: { 'Content-Type': 'application/json', ...options.headers } }) return await res.json() } finally { clearTimeout(timer) } }

这个超时设计虽然简单，但在生产环境中救了我很多次。有一次内容服务因发布故障导致响应时间飙到 15 秒，就是靠这个超时控制，前端页面才能在三秒内返回降级数据，没有拖垮整个页面。

6. 实操过程：从初始化项目到完成首次渲染

6.1 用 Vite 快速初始化 Vue3 项目

初始化项目我推荐直接使用 Vite 官方脚手架，这比自己从头配置省很多事。以下命令会创建一个 Vue3 加 JavaScript 的工程模板：

npm create vite@latest vue3-ssr-demo -- --template vue cd vue3-ssr-demo npm install

创建完以后，需要安装 SSR 相关的额外依赖。由于 SSR 和 BFF 层都需要用到，我建议直接全部安装：

npm install pinia @vue/server-renderer npm install -D concurrently cross-env

concurrently是用来同时启动多个进程的，后面在开发模式下，我需要同时启动 Vite 开发服务器和 Node BFF 服务，这个工具就是干这个用的。

6.2 改造目录结构和入口文件

脚手架的默认结构里只有index.html和src/main.js，我需要改造成双入口模式。操作步骤参照我在前面列的目录结构，新增entry-client.js和entry-server.js，把原来main.js的内容抽到一个公共的工厂函数里，让两个入口共同使用。

// main.js import { createSSRApp } from 'vue' import { createPinia } from 'pinia' import App from './App.vue' import { createRouter } from './router' export function createApp() { const app = createSSRApp(App) const pinia = createPinia() const router = createRouter() app.use(pinia) app.use(router) return { app, router, pinia } }

注意这里统一用的是createSSRApp，而不是createApp。createSSRApp专门用于 SSR 场景，它在服务端渲染时性能更好，同时会自动跳过一些只能在浏览器中执行的组件生命周期函数。

6.3 开发模式下的双服务协同

开发模式下的架构是这样的：浏览器请求先发到才创建的 Node BFF 服务，BFF 服务再把请求转发给 Vite Dev Server，由 Vite 编译服务端代码并渲染出 HTML。这种方式的优点是可以同时享受 Vite 热更新和 BFF 层的数据聚合能力。

为了实现这个效果，我用concurrently写了两个启动命令：

{ "scripts": { "dev": "concurrently \"npm run dev:vite\" \"npm run dev:bff\"", "dev:vite": "vite", "dev:bff": "node bff/server.js" } }

BFF 服务里需要判断当前是否是开发环境，如果是，就把 HTML 请求转发给 Vite 的中间件，由 Vite 实时编译组件；如果是生产环境，直接读取打包好的 HTML 模板合并渲染结果即可。这段判断逻辑可以从环境变量里读。

const isProd = process.env.NODE_ENV === 'production' if (isProd) { const template = fs.readFileSync(resolve('dist/client/index.html'), 'utf-8') app.use(async (req, res) => { // 读取打包产物中的 manifest 和渲染结果 }) } else { const vite = await createServer({ server: { middlewareMode: true }, appType: 'custom' }) app.use(vite.middlewares) }

6.4 生产构建时如何正确处理静态资源路径

生产构建是 SSR 项目最容易出问题的环节之一。客户端资源打包后默认放在dist/client目录，但服务端渲染的 HTML 如果引用的 JS 路径写成/assets/index-xxx.js，部署到服务器时如果用了子路径，比如放在https://example.com/ssr-app/下，这个绝对路径就会 404。

我的解决方案是给 Vite 配置base参数，让它按部署路径生成资源引用前缀：

export default defineConfig({ base: process.env.NODE_ENV === 'production' ? '/ssr-app/' : '/', // ...其他配置 })

这样就确保了打包后的 HTML 中，所有 script 和 link 标签的资源路径都带上了正确的子路径前缀。

6.5 首次渲染验证的检查清单

当你跑通整个流程，能成功把页面返回到浏览器时，先别急着高兴，花五分钟检查以下四个点。第一，右键查看网页源代码，看是否能看到完整的页面内容，而不是一个空的<div id="app"></div>；第二，打开浏览器开发者工具的网络面板，确认只发出了一个页面请求，BFF 层内部的数据聚合请求不会出现在浏览器请求列表中；第三，切换页面路由时，看看是否走了客户端路由还是服务端整页刷新；第四，刷新页面时检查控制台是否有水合警告，比如 "Hydration completed but contains mismatches" 之类的报错。如果这四个点都正常，说明 SSR 链路基本打通了。

7. 常见问题与排查技巧实录

7.1 PowerShell 禁止运行脚本导致 npm 命令不可用

热搜词里专门有一句很长的报错：“npm : 无法加载文件 d:\node\npm.ps1,因为在此系统上禁止运行脚本。”这个问题的本质是 Windows PowerShell 的权限策略默认只允许运行签名脚本，而 npm 生成的.ps1没有签名。解决办法很简单，用管理员权限打开 PowerShell，执行以下命令：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

这个命令表示允许运行本地创建的脚本和远程下载但经过签名的脚本，安全性还可以接受。如果实在不想动执行策略，也可以改用cmd命令行窗口来运行 npm 命令，那里面不受 PowerShell 的脚本策略限制。

7.2 Node 报错：requested module 'node:util' does not provide an export named

我在参与的这个项目初期，把 Node 从 16 升到 18 之后，代码突然报错SyntaxError: the requested module 'node:util' does not provide an export named。这个问题刚开始看前缀以为是 Node 自带模块的问题，排查很久后才发现是某个依赖库用了较新 Node 才能提供的node:util导出名，而实际运行的 Node 版本太低，导出表里没有这些新成员。

解决思路是先确认 Node 版本，如果代码是新的，直接升级到 Node 18 以上基本能解决。如果升级后还有问题，再检查一下是哪个依赖库导致的，用npm ls util或node -e "console.log(require.resolve('util'))"慢慢排查。类似的问题还有报Cannot find module 'node:path'或者requested module 'node:stream' does not provide an export named，这些基本都是版本不匹配导致的，排查思路一致。

7.3 文件分片上传时报 request aborted

热搜词里还有一句是关于文件分片上传时后台报了一个request aborted错误。这个问题发生的原因通常有两个。第一个原因是前端在发送分片请求时设置了超时时间，数据还没传完就被前端给中断了；第二个原因是 Node 服务端设置的超时时间太短，或者请求体体积限制太小，导致 Node 主动中断了正在处理中的请求。

我建议排查顺序如下：先看前端有没有对分片请求设置超时，如果有，把超时时间调大到 5 分钟以上；再检查 BFF 层是否设置了server.requestTimeout和server.headersTimeout，默认值在 Node 17 之后变成了 300 秒，应该已经够用了；最后看一下网关层或者 Nginx 的client_max_body_size配置，如果传大文件时中间层拒绝接收，一样会表现为 request aborted。

7.4 开发时 Vue3 路由跳转后组件内容不渲染

这个问题发生在开发环境下：路由地址变了，地址栏 URL 正确，但是页面内容没有更新。排查下来发现是因为我在组件里用了原生异步接口请求数据，路由跳转后组件虽然重新渲染了，但数据还在请求中，导致页面看起来像“没变化”。本质上不是路由问题，而是数据加载时机没控制好。

解决思路有两种。对于 SSR 场景，把数据预取逻辑放到onServerPrefetch钩子中，服务端渲染时把数据取好，客户端拿到后直接显示，就不会出现闪烁空白的问题。对于纯客户端场景，在路由的beforeEnter钩子里用await等待数据请求完成后再放行，也能达到类似的效果。

7.5 v-if 与 v-show 在 SSR 中的差异

如果稍不注意在服务端渲染的组件里混用v-if和v-show，会引发水合警告。v-show的原理是通过 CSS 样式控制显示隐藏，但它要求元素必须在 DOM 中真实存在，而服务端渲染后的 HTML 中，标签结构必须和客户端完全一致，否则水合时就会报 mismatch。

这个问题的解决方案就是遵循一个原则：可以改变 DOM 结构的需求用v-if，只做样式切换的需求用v-show。在使用v-show时，保证初始状态下的显示隐藏判断在服务端和客户端结果相同，不要依赖浏览器特性，比如window.innerWidth这类值在服务端是不存在的。

7.6 常见问题速查表

其中pxtorem对应的这个问题也是实际开发中经常碰到的，Vue3 项目里如果配置了 pxtorem 插件，你会发现在 echarts 的配置项里写width: 100这种数值并不会被自动转换成 rem，因为 pxtorem 只处理样式表中的 px 单位，JavaScript 里动态设置的像素值它管不到。解决方式就是自己写一个 rem 封装函数，把入口处的像素值根据基准大小换算。

8. 开发中的一些独门心得

8.1 服务端渲染时要学会“放过”自己

很多人第一次做 SSR 容易陷入一个误区，觉得所有组件都应该在服务端渲染成完整 HTML。但实际上，某些组件的渲染重度依赖浏览器 API，或者包含大量不被搜索引擎关注的动态交互逻辑，强行塞到服务端只会带来无穷无尽的水合警告和性能损耗。

我的策略是区分页面的关键度。内容页、列表页这些需要被搜索引擎收录的页面，必须完整服务端渲染；后台管理系统里的图表、富文本编辑器这类交互组件，用<ClientOnly>包装起来，只在客户端渲染。这种混合方式既保证 SEO，又降低了 SSR 的复杂度和排错成本。

8.2 BFF 层的代码一定要保持轻量

BFF 层是任何前后端交互的必经之路，但它不应该承担太重的业务逻辑。在我见过的一些失败案例里，团队把业务校验、权限判断、甚至部分数据计算都塞进了 BFF 层，最后 BFF 层代码越写越多，变成了一个难维护的“二道贩子”。

我的建议是：BFF 层只做三件事——路由转发、数据聚合、结果缓存。任何超过十行的业务逻辑，要么下沉到后端服务，要么上提到前端组件。如果一个接口处理器超过五十行，就要考虑拆分了。保持 BFF 层的轻量化，最终受益的还是前端团队自己。

8.3 无论如何都要写单元测试和记录

SSR 项目里最怕的就是改动某个公共组件，结果影响到了服务端渲染的结果。我在这个项目后段给 BFF 层的核心聚合接口写了简单的单元测试，用的是 Node 内置的node:test模块，不需要额外安装测试框架。测试内容重点覆盖接口并发调用、超时降级、缓存命中这三个场景。虽然测试不算全面，但每次改动后跑一遍测试，心里就踏实很多。

同时，每个后端服务的接口返回结构如果发生了变化，BFF 层的字段映射也要跟着改。建议在项目里维护一份接口契约清单，标注清楚哪个接口用了哪些字段、这些字段来自哪里，别等到搭完了才想起来查。

9. 部署与上线阶段要注意的细节

9.1 进程守护与端口转发

生产环境的 Node BFF 服务不能裸跑，需要用一个进程守护工具来管理。我用的pm2，它可以在进程崩溃时自动重启，也支持日志收集。配置文件非常简单：

// ecosystem.config.js module.exports = { apps: [{ name: 'vue3-ssr-bff', script: 'bff/server.js', instances: 2, exec_mode: 'cluster', env: { NODE_ENV: 'production', PORT: 3000 } }] }

instances: 2表示用两个进程实例跑同一个服务，Node 是单线程的，多开进程能利用多核 CPU 提高吞吐量。前面用 Nginx 做反向代理时，把/路径转发到 3000 端口。

9.2 缓存策略和静态资源处理

服务端渲染的页面虽然每个请求都会走到 Node 服务，但动态性不强的页面可以加上缓存。我在 BFF 层里给内容列表接口加了 30 秒缓存，给用户详情接口做了 5 秒缓存，既保证数据新鲜度，又减少了后端服务压力。

静态资源则由 Nginx 直接服务于客户端构建产物所在的目录，完全不需要经过 Node 进程。由于资源文件名带了内容哈希，可以放心设置Cache-Control: public, max-age=31536000, immutable来做永久缓存，减少用户重复加载时的流量消耗。

9.3 监控与日志

线上服务不能没有监控。除了 pm2 自带的日志外，我还加了一个很轻量的请求日志中间件，记录每个请求的耗时、状态码、来源 IP。这段逻辑放在 BFF 层的最外层，即收到请求时记录开始时间，响应结束后计算耗时并写入日志文件。

别小看这个简单的日志，当你遇到线上偶发 500 错误或者接口响应慢的投诉时，这份日志就是第一手的排查依据。我遇到过一次诡异的线上超时问题，就是靠日志发现有一个请求在 BFF 层耗时 12 秒，再往下追才发现是后端服务的某个查询在特定参数下没有走索引。

10. 最后再分享几个小技巧

踩过这么多坑之后，我总结了几条值得单独拎出来的经验，希望能帮你少走弯路。

第一，开发 SSR 项目时，不要从零开始写脚手架。Vue 官方和 Vite 官方都有现成的 SSR 模板示例，虽然功能比较简单，但作为起点足够稳定，后续再逐步添加自己的 BFF 层和业务页面。

第二，遇到服务端渲染的水合错误，不要急着改代码。先在浏览器里查看网络响应，把服务端返回的 HTML 和浏览器实时的 DOM 做一次对比，找出第一处不一致的地方往往就能定位问题根源。大部分 mismatch 都出在时间格式、随机数、浏览器环境判断这些细节上。

第三，BFF 层的关键接口一定要做降级。后端服务不可用，前端至少还能渲染一个提示页面，而不是整个页面白屏。做降级并不需要复杂的设计，BFF 层在捕获异常后返回一个code: 500的结构，前端拿到后渲染兜底组件，这个套路就够用。

第四，NVM 安装 Node 之后，npm命令找不到的情况也会碰到。运行nvm use default重新激活一次，大多数时候就能解决。

做 Vue3 SSR 加 Node BFF 这个项目，过程确实不算轻松，但做完之后我对前端架构的理解又深了一层。以前觉得服务端渲染是后端的事，BFF 是运维的事，真正动手之后才发现，这中间有大量细节是需要全栈视野才能把控的。希望这篇记录能帮你更顺利地搭出自己的项目，代码我都放在开源仓库里了，遇到问题可以直接对照着排查。