我做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 idapp/div和一堆script标签。浏览器需要先把JS bundle下载下来再解析执行创建Vue应用实例挂载到DOM上页面才开始有内容。这个过程中用户看到的就是白屏。你可以把这种模式类比成去餐厅吃饭菜单要先从厨房现印你拿到菜单后才能点菜后厨再开工。而SSR是服务员直接给你端来一桌已经做好的菜你坐下来就能动筷子甚至某些配菜在你坐下之前就已经摆在桌上了。差别就在这里。我实测过一个中等规模后台项目生产环境gzip后的JS chunk大约1.2MB首屏渲染链路要经历“下载HTML→下载JS→解析执行→创建应用→路由匹配→渲染组件”在普通的4G网络和千元机上白屏时间稳定在3到5秒。换成SSR后服务端把关键内容的HTML字符串拼好返回用户第一眼就能看到页面主体JS继续在后台做水合体验差距非常明显。这里强调一下SSR主要优化的是“首屏内容呈现时间”不是“交互可用时间”。TTITime 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服务端引擎、文件式路由、自动导入、数据获取APIuseFetch/useAsyncData、useSeoMeta、布局系统。如果你是新项目需求是快速上线一个标准的SSR应用Nuxt 3几乎是最高效的选择。Nuxt 3的抽象层省事也意味着你要接受它的约定。路由生成是文件目录优先项目结构必须按它的规则摆放服务端逻辑的编写方式、API接口的组织、数据获取时机都由框架替你安排。当你需要深度定制渲染管线或者项目里大量模块是从老Vue项目迁移过来的约束感会很明显。我遇到的具体问题是现有项目有十多个老模块路由模式、权限校验、主题配置都是自定义的迁到Nuxt相当于把这些逻辑全部重写一遍还要适配它的钩子体系。成本比自建SSR高得多所以我最终选了原生Vue。2.3 一个可参考的决策标准我用一个相对固化的标准来决策维度原生Vue SSRNuxt 3新项目快速上线一般要自己拼装快开箱即用老Vue项目渐进改造适合迁移成本高深度定制渲染管线完全可控受框架约束学习成本高需理解SSR原理中需理解Nuxt约定生态扩展直接用Vue生态库优先用Nuxt模块体系部署要求需Node进程或自定义适配内置Nitro支持多种部署长期维护工程化能力要求高框架升级时需跟进一句话总结想让团队快速拥有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.vuepackage.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 idapp!--app-html--/div scriptwindow.__PINIA_STATE__ !--pinia-state--/scriptpinia.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 scriptwindow.__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在服务端模板里加上relpreload首屏性能优化很明显。进程守护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原理依然有效只是很多细节由框架替你处理了。两条路都值得走重要的是先理解服务端渲染到底在做什么再决定让工具帮你做到哪一步。
 项目介绍,路由配置,vant组件库的下载和使用)
