企业官网建设流程全解析

我做Vue项目开发这些年，花时间最多、收益最明显的一块，居然是被业务方逼着补上的SSR。起因是一个品牌官网，SEO一直抓不到内容，首页白屏稳定在4秒以上，市场部天天催，开发组内部又僵在“继续加loading动画等SPA渲染”还是“用Nuxt重写”之间。后来我把原生Vue 3 + Vite的服务端渲染(SSR)方案完整跑通，才发现这件事并没有想的那么玄——它要解决的核心就两个：首屏性能和SEO抓取。如果你手里的Vue项目也是内容型、营销型、或者需要被搜索引擎认真收录的应用，这篇文章就是把你从纯前端CSR的舒适区拉出来，讲清楚SSR能做什么、怎么做、会遇到哪些坑，并且给出一套能直接参考的实现。

你可能已经掌握了Vue组件、路由、Pinia、构建工具这些基础，走到“第52天”这个阶段，项目要上线、要面对真实流量了，SSR不再是一个高阶炫技话题，而是一个必须认真对待的工程选项。这篇内容以原生Vue 3 + Vite + Express为基础，不依赖Nuxt，让你既能理解SSR的底层原理，也能把这套工程化方案搬到自己的项目里。

1. SSR到底解决了什么问题

很多人一听到SSR，第一反应是“为了SEO”。这个说法对，但只说对了一半。服务端渲染实际解决的是一组互为因果的Web应用问题，只是SEO最容易被老板和运营感知到。我们先把这个逻辑拆开，后面做技术选型和架构设计才有依据。

1.1 首屏性能差的根源不在网络，在“先下载再渲染”

纯前端SPA的运行链路是这样的：用户请求一个页面，服务器返回一个几乎空的HTML骨架，里面就一个<div id="app"></div>和一堆script标签。浏览器需要先把JS bundle下载下来，再解析执行，创建Vue应用实例，挂载到DOM上，页面才开始有内容。这个过程中，用户看到的就是白屏。

你可以把这种模式类比成去餐厅吃饭，菜单要先从厨房现印，你拿到菜单后才能点菜，后厨再开工。而SSR是服务员直接给你端来一桌已经做好的菜，你坐下来就能动筷子，甚至某些配菜在你坐下之前就已经摆在桌上了。差别就在这里。

我实测过一个中等规模后台项目，生产环境gzip后的JS chunk大约1.2MB，首屏渲染链路要经历“下载HTML→下载JS→解析执行→创建应用→路由匹配→渲染组件”，在普通的4G网络和千元机上，白屏时间稳定在3到5秒。换成SSR后，服务端把关键内容的HTML字符串拼好返回，用户第一眼就能看到页面主体，JS继续在后台做水合，体验差距非常明显。

这里强调一下，SSR主要优化的是“首屏内容呈现时间”，不是“交互可用时间”。TTI（Time to Interactive）不会因为SSR自动变短，你依然需要做代码分割、懒加载、资源压缩，这些组合拳缺一不可。

1.2 SEO对JS渲染的容忍度没有想象中那么高

搜索引擎爬虫这些年确实进化了，主流搜索引擎宣称能执行JavaScript，但实际抓取和索引过程中，爬虫调度、渲染队列、抓取预算都是现实约束。一个内容频繁更新的站点，如果搜索引擎每次都要等JS执行完才能拿到正文，索引速度和覆盖率都会受影响。

有人会说“Google已经很支持SPA了”，但投放市场的站点不只有海外搜索，国内主流搜索引擎对JS渲染的支持程度差异很大，有些甚至默认不执行JS。即使支持，爬虫也要额外排队渲染一次，发现和收录的时效性就会打折扣。对于依赖自然流量、需要快速收录的页面，纯前端方案确实不友好。

SSR把内容直接放在HTML里，爬虫拿到HTML就能解析到完整正文、标题、meta信息，不需要额外等待。配合合理的meta管理，每个路由都可以输出独立的title和description，这是纯SPA很难做到的——因为SPA不管切到哪个路由，HTML里的title始终是index.html里那一个。

1.3 CSR、SSR、SSG怎么选

• CSR（客户端渲染）：适合后台管理、需要强交互、对SEO无要求的应用，开发模式最轻。
• SSG（静态站点生成）：适合内容基本不变或周期性变化的公开页面，构建时生成HTML，性能最好，部署成本最低。
• SSR（服务端渲染）：适合内容动态变化、依赖用户状态或实时数据的页面，既要SEO又要动态性。

实际项目中很少是单一模式。我的常规做法是：公开内容多的页面用SSR或SSG，后台全用CSR，两者在同一个应用里共存。Vue 3生态完全支持这个混合诉求，不需要二选一，这也是我后来坚持用原生Vue建SSR而不是直接迁到Nuxt的原因之一——我的项目里有一部分页面本来就是纯客户端交互逻辑，结构完全不一样。

2. 技术选型：原生Vue SSR还是Nuxt 3

确认要做SSR之后，第一个纠结就是选哪条路。原生Vue SSR和Nuxt 3都能实现目标，但它们解决的问题层次完全不同。我当时把两边的方案都跑了一轮demo，才确定用原生Vue。下面把这两条路的真实成本讲清楚。

2.1 原生Vue SSR要自己扛什么

原生Vue SSR的核心理念是“你的应用还是这个Vue应用，只是多了一个服务端入口”。你需要自己组织这些模块：

• 服务端入口：用createSSRApp创建应用实例，处理路由匹配、数据预取，最终调用renderToString输出HTML字符串。
• 客户端入口：创建另一个应用实例，执行水合（hydration）逻辑，让事件绑定和交互逻辑在浏览器端接管DOM。
• 数据预取协议：约定组件如何声明需要的数据、服务端如何触发这些数据请求、状态如何序列化注入到客户端。
• 构建配置：同一套代码要分别构建出客户端产物和服务端产物。
• 服务端承载：需要一个Node服务跑渲染逻辑，处理静态资源、错误、并发。
• 部署环境：SSR进程需要常驻，要考虑内存、故障重启、进程守护。

每个模块都不复杂，但串起来就是一个完整工程，踩坑概率高。它的优势也很明显：完全可控。路由守卫、Pinia、组件懒加载、中间件，这些第三方库和原生Vue的全部能力你都能直接使用，不会被框架的约定束缚。

2.2 Nuxt 3帮你省掉什么、增加什么成本

Nuxt 3是Vue生态里最成熟的SSR方案，它内置了Nitro服务端引擎、文件式路由、自动导入、数据获取API（useFetch/useAsyncData）、useSeoMeta、布局系统。如果你是新项目，需求是快速上线一个标准的SSR应用，Nuxt 3几乎是最高效的选择。

Nuxt 3的抽象层省事，也意味着你要接受它的约定。路由生成是文件目录优先，项目结构必须按它的规则摆放；服务端逻辑的编写方式、API接口的组织、数据获取时机，都由框架替你安排。当你需要深度定制渲染管线，或者项目里大量模块是从老Vue项目迁移过来的，约束感会很明显。

我遇到的具体问题是：现有项目有十多个老模块，路由模式、权限校验、主题配置都是自定义的，迁到Nuxt相当于把这些逻辑全部重写一遍，还要适配它的钩子体系。成本比自建SSR高得多，所以我最终选了原生Vue。

2.3 一个可参考的决策标准

我用一个相对固化的标准来决策：

一句话总结：想让团队快速拥有SSR能力、项目又能接受框架约束，选Nuxt 3；如果我要的是“把SSR无缝嵌进现有Vue工程”，且团队里有能驾驭构建和Node层的人，原生Vue SSR反而是更省心的路。

3. 从零搭建Vue 3 + Vite SSR项目

这里给你一套能参考的原生Vue 3 + Vite + Express的SSR实现。我会把目录结构、服务端入口、客户端入口、数据预取、节点服务串起来，你可以直接照着复现，再按业务需要扩展。

提示：以下代码以Vue 3.4、Vite 5、Express 4为基准。Vite和Express的API在不同版本间有差异，遇到报错优先检查版本，不要急着怀疑代码逻辑。

3.1 双入口双构建，先把目录理清楚

SSR项目的第一个特点就是“同一个应用，两个入口”。这是必须在一开始就建立的认知，否则后续所有代码看起来都很别扭。

project/ ├── index.html # 客户端构建用HTML模板 ├── server.js # Express服务端，生产环境使用 ├── vite.config.js # Vite配置 ├── src/ │ ├── entry-client.js # 客户端入口，负责水合 │ ├── entry-server.js # 服务端入口，负责渲染HTML │ ├── App.vue │ ├── router/ │ │ └── index.js # 路由配置，双端共用 │ ├── stores/ │ │ ├── index.js # 创建Pinia实例 │ │ └── article.js # 文章store │ └── views/ │ ├── Home.vue │ └── Article.vue

package.json里的构建脚本至少要有：

{ "scripts": { "build:client": "vite build --outDir dist/client", "build:server": "vite build --ssr src/entry-server.js --outDir dist/server", "build": "npm run build:client && npm run build:server", "serve": "node server.js" } }

注意构建顺序：必须先构建客户端，再构建服务端。因为服务端的入口会引用客户端构建产物的路径信息，而且生产环境的server.js需要读取dist/client/index.html作为模板。很多人第一次跑脚本报“模板不存在”，就是这个顺序搞反了。

3.2 服务端渲染入口怎么写

服务端入口的思想就是：为当前请求的URL创建一个全新的应用实例，把路由推进到对应页面，等待数据就绪，然后渲染出HTML。

// src/entry-server.js import { createSSRApp } from 'vue' import { renderToString } from 'vue/server-renderer' import { createPinia } from 'pinia' import { createMemoryHistory } from 'vue-router' import App from './App.vue' import { createRouter } from './router' import { getAsyncData } from './helpers/asyncData' export async function render(url) { const app = createSSRApp(App) const pinia = createPinia() const router = createRouter(createMemoryHistory()) app.use(pinia) app.use(router) await router.push(url) await router.isReady() // 执行路由匹配到的组件中声明的 asyncData const matched = router.currentRoute.value.matched const components = matched.flatMap(record => Object.values(record.components || {}) ) await Promise.all( components .filter(comp => comp.asyncData) .map(comp => comp.asyncData({ pinia, route: router.currentRoute.value })) ) const html = await renderToString(app) return { html, piniaState: pinia.state.value } }

这段代码有两个关键点。

第一，createSSRApp和createApp的区别。服务端每个请求都必须新建应用实例，不能复用全局单例，否则不同用户的登录态、页面数据会互相污染。createSSRApp是服务端渲染专用的入口，它在内部处理了组件实例的作用域隔离，比createApp更适合这个场景。

第二，数据预取。我这里的约定是组件如果定义了asyncData方法，服务端就会在渲染前调用它。asyncData收到的pinia实例用于写入服务端请求到的数据，这样组件在服务端渲染时，模板里已经能拿到完整内容。这个协议简洁直观，可以在团队里当约定用。Vue 3也提供了onServerPrefetch钩子，适合在组件setup阶段直接写预取逻辑，但需要自行管理Promise完成时机，我更喜欢集中式asyncData，排查数据流时一眼就能看清。

3.3 客户端水合入口与状态注入

客户端入口负责两件事：把服务端注入的状态恢复到自己的Pinia实例里，并接管DOM完成交互事件绑定。

// src/entry-client.js import { createSSRApp } from 'vue' import { createPinia } from 'pinia' import { createWebHistory } from 'vue-router' import App from './App.vue' import { createRouter } from './router' const pinia = createPinia() // 恢复服务端注入的状态 if (window.__PINIA_STATE__) { pinia.state.value = JSON.parse(window.__PINIA_STATE__) } const router = createRouter(createWebHistory()) const app = createSSRApp(App) app.use(pinia) app.use(router) router.isReady().then(() => { app.mount('#app') })

服务端状态注入的对接方式，你要在返回的HTML里手动塞一段<script>。如果模板是index.html，常见做法是在模板里预留占位符，然后在服务端渲染函数里替换：

<!-- index.html 模板片段 --> <div id="app"><!--app-html--></div> <script>window.__PINIA_STATE__ = <!--pinia-state--></script>

pinia.state.value在服务端是一个普通的响应式对象，序列化成JSON后塞进占位符。注意JSON.stringify的结果如果是undefined或空对象，要处理边界情况，否则会输出undefined字符串导致客户端JSON.parse报错。

客户端为什么叫“水合”？因为服务端已经把DOM渲染好了，客户端如果直接app.mount('#app')，Vue会对比服务端生成的DOM结构和客户端首次渲染的虚拟DOM结构，一致则复用已有DOM，只绑定事件，这叫水合（hydration）。如果两边不一致，Vue会警告并强制重新渲染，轻则闪烁，重则整个首屏交互错乱。

3.4 承载渲染的Node服务与HTML模板

生产环境下，需要一个Node服务来做三件事：托管静态资源、调用服务端渲染入口、返回拼好的完整HTML。

// server.js import express from 'express' import { readFileSync } from 'fs' import { resolve, dirname } from 'path' import { fileURLToPath } from 'url' import { render } from './dist/server/entry-server.js' const __dirname = dirname(fileURLToPath(import.meta.url)) const template = readFileSync(resolve(__dirname, 'dist/client/index.html'), 'utf-8') const app = express() // 静态资源：客户端构建出的js/css，让浏览器直接请求 app.use('/assets', express.static(resolve(__dirname, 'dist/client/assets'))) // 所有非静态请求都交给SSR处理 app.use(async (req, res) => { try { const { html, piniaState } = await render(req.url) const stateScript = `<script>window.__PINIA_STATE__ = ${JSON.stringify(piniaState)}</script>` const fullHtml = template .replace('<!--app-html-->', html) .replace('<!--pinia-state-->', stateScript) res.status(200).type('text/html').send(fullHtml) } catch (err) { console.error('SSR render failed:', err) res.status(500).send('Server Error') } }) app.listen(3000, () => { console.log('SSR server running at http://localhost:3000') })

这里静态资源路径需要和客户端构建的base配置、实际部署路径对应。Vite默认输出到/assets，如果你的资源部署在CDN，把base改成CDN地址即可，服务端模板里的资源前缀会自动跟着变。

还有一个我踩过的坑：Express 5的路径匹配语法变了，app.get('*', ...)会直接抛错，要用app.use或者app.get(/.*/)来兜底。所以上面的代码直接用app.use处理所有未被前面的静态资源中间件匹配的请求，更兼容。

3.5 首屏性能与SEO的配套优化

SSR只是把渲染时机提前了，要真正提升首屏体验，还要叠加几层优化：

• 路由级代码分割：让首屏只加载当前路由需要的JS chunk。Vue Router的懒加载写法在SSR下依然生效，组件定义用() => import('./views/Home.vue')即可。
• 静态资源压缩：服务端返回前做gzip/br压缩，Express可以接compression中间件，能减少约70%的传输体积。
• 关键CSS内联：首屏路径组件用到的CSS如果能内联到HTML，可以省掉一次CSS文件请求的往返，尤其适合内容型页面。
• 缓存策略：对不依赖用户态的动态页面，可以在服务端做一层渲染缓存，命中缓存的请求直接返回HTML，减轻Node进程压力，TTFB能降到个位数毫秒级。
• meta管理：SSR解决了内容收录，title和description还得每个路由自己输出。可以在服务端匹配路由meta后，动态替换模板里的<title>和<meta>标签，比SPA里改document.title更彻底，爬虫看到的都是完整信息。

SEO这块我再提一句：链接结构、sitemap、结构化数据这些传统SEO手段，在SSR项目里同样要做。SSR解决的是“爬虫能读到内容”，但这些决定了你被收录后的展示质量。

4. 实战中踩过的坑与排查清单

SSR项目从能跑到跑得稳，中间隔着大量细节。这里记录的问题，每一个都是我实际碰到并排查过的。把它们整理成清单，你遇到类似情况时有地方可查。

4.1 hydration mismatch：最典型的SSR翻车现场

现象：浏览器控制台出现“Hydration completed but contains mismatches”警告，页面可能出现闪烁、事件不生效、样式错乱。

原因：服务端渲染出的HTML和客户端首次渲染的结构不一致。常见触发点有三个：

• 渲染内容依赖window、document、localStorage等浏览器全局对象。
• 渲染内容包含当前时间、随机数、设备信息等每请求都变的数值。
• 第三方组件在服务端环境下输出空内容，客户端才正常渲染。

解决思路：不要让服务端和客户端出现“第一次渲染结果不同”的情况。如果某些内容必须依赖浏览器环境，用Vue 3的<ClientOnly>包装，或者在组件里先渲染占位内容，到客户端mounted后再填充真实内容。时间、随机数这类，统一在onMounted里处理，保证服务端输出的是稳定的初始值。

另一个容易忽略的：某些组件内部样式会根据媒体查询或者屏幕宽度改变DOM，这类动态DOM尽量下沉到mounted阶段再操作，不在首屏渲染时直接输出。

4.2 跨请求状态污染与内存泄漏

SSR服务是长驻进程，所有请求共享同一个Node进程。如果应用实例、Pinia store、Vue Router实例被设计成全局单例，第一个请求写入的数据会残留在进程里，第二个用户拿到的是上一个用户的数据。这种bug极其隐蔽，因为它不报错，只有在用户量大、并发高的时候数据才会串。

解决办法就是文章前面强调的：每个请求内都调用工厂函数创建全新的应用实例、Pinia实例、Router实例。排查时看代码里有没有模块级let app、未释放的setInterval、挂在全局对象上的引用。线上如果出现内存只增不减，优先怀疑是不是有全局缓存、未清理的监听器或定时器。

还有一个实践心得：在asyncData里发起HTTP请求时，一定要设置超时。服务端一旦卡在请求上，会直接拖垮整个Node进程。给自己的请求库统一配置超时，失败时降级返回默认数据，这是SSR服务稳定性的基础。

4.3 服务端没有window：第三方库与浏览器API

现象：启动服务端渲染时，某个第三方库直接报错“window is not defined”。

原因：很多UI库、图表库、地图库在引入时就会访问浏览器API，或者它们的组件内部渲染时用了document.getElementById。

解决办法：这类组件不能直接走SSR渲染，用动态导入组件的方案，让它在服务端构建时被排除：

// 动态导入并标记为非SSR const ClientOnlyComponent = defineAsyncComponent(() => import('./HeavyChart.vue'))

也可以再用<ClientOnly>把依赖浏览器环境的组件包一层，确保服务端不渲染这个分支。第三种做法是在build:server的构建配置里，把这些库标记为external或者替换为空的mock模块。具体用哪个取决于库的接入方式，但核心原则不变：服务端只负责输出稳定HTML，所有依赖浏览器的能力都推迟到客户端。

我在项目里碰到过最典型的是腾讯地图组件，在服务端完全无法初始化，用上述方案切到客户端渲染后，问题消失。SSR和第三方浏览器库的冲突，处理起来可以很机械。

4.4 构建与部署环节的几个细节

构建阶段容易踩的坑：

• failed to load tsconfig '@vue/tsconfig/tsconfig.web.json'：这是Vue官方工具链项目常见问题，本质是缺少@vue/tsconfig依赖。不用改tsconfig内容，直接安装它：

npm install -D @vue/tsconfig

• 构建产物体积：服务端构建产物很大不代表有问题，因为Node端不压缩不影响浏览器。但客户端构建产物要重点关注chunk切割，避免首屏的entry-clientchunk过于庞大。我在生产项目里把三方依赖单独拆成vendorchunk，在服务端模板里加上rel="preload"，首屏性能优化很明显。
• 进程守护：SSR服务必须用PM2或systemd守护，进程崩了要能自动拉起。PM2的instances可以设置成CPU核数，实现多进程负载。注意多进程下如果做了内存缓存，要处理好缓存一致性。我的做法是只缓存不依赖登录态的公开页面，用户态的请求不走缓存。
• 健康检查：给服务端加一个/healthz路径，返回200，配合负载均衡做健康检查，防止有问题的实例被调度到流量。
• 版本管理：Vite、Vue、vue-router、pinia的版本组合要提前锁好。Vite的SSR构建在5.x版本里已经相当成熟，但我仍建议在依赖里手动钉版本，避免大版本自动升级后构建产物行为变化。

写在最后：SSR这件事的个人心得

上面这套方案，我是从零开始摸索，中间踩过的坑比写的还要多。跑通那天，我做的第一件事就是把首页从CSR切到SSR，用Chrome的Lighthouse重新测了一遍：首屏内容呈现时间从4秒多降到1秒以内，模拟爬虫抓取HTML，正文、标题、meta全部都在。那种满足感是真实存在的。

我的体会是：SSR不是银弹，它只是换了一种渲染时机，同时把工作量从浏览器端挪到了服务端。如果项目里的页面多数不需要SEO，纯CSR仍然最划算；如果你要做的站点靠内容获客、靠搜索引擎带流量，SSR就是核心能力而不仅仅是优化项。

我最终常驻的方案是混合渲染：公开内容页走SSR，后台全部走CSR，两者在同一个Vue应用里共存。这套方案上线后稳定运行了大半年，除了偶尔的第三方库兼容问题，没有出过大故障。如果你正好处在“Vue基础已经熟悉，想进一步做真实项目”的阶段，我建议你亲手搭一次SSR，不要只停留在会看文档的层面。把双入口跑通、把数据预取摸透、把水合警告调没，这一套流程下来，你对Vue应用生命周期的理解会比看十遍文档都深。

如果你打算用Nuxt 3，上面的SSR原理依然有效，只是很多细节由框架替你处理了。两条路都值得走，重要的是先理解服务端渲染到底在做什么，再决定让工具帮你做到哪一步。