服务端渲染:Nuxt 4 与 SEO 实战
本篇要点:能按 URL 分档为每类页面选一种渲染方式,写进
routeRules,并用可量化的命令验收首屏 HTML。 前置文章:《测试与质量:Vitest 组件测试与 Playwright E2E》让改动有了自动化门禁,这一章解决《性能优化:渲染性能、长列表与加载策略》没解决的另一半——首屏内容根本不在 HTML 里。
为什么需要它
一个 SPA 站点,站点地图 12.4 万条 URL,Search Console 里"已编入索引"只占 41%,"已发现尚未编入索引"的平均滞留 9.6 天。移动端 4G 模拟下 LCP(Largest Contentful Paint,最大内容绘制)中位数 2.8 秒,其中 71% 花在 JS 下载与执行上。
"SPA 不利于 SEO"这个说法并不准确。Googlebot 有能力执行 JS,问题出在排队:它把"执行 JS 后取内容"排在"解析 HTML 即取内容"之后,URL 一多,延迟就是天级。另有一类抓取器完全不执行 JS——社交平台的卡片预览、部分聚合器、企业内部知识检索,在这些场景下 SPA 交上去的 og:image 是空的。
所以要做的事不是"上 SSR",而是让首屏 HTML 自己带正文。验收对象应该是 HTML 本身:关掉 JS,页面上还能看到正文。如果把验收写成"用了 SSR",就无法排除服务端渲染了个空壳、内容仍靠客户端补齐。
迁移范围也要先划清。需要进入搜索结果的 URL 占全站 PV 的 62%(口径:2026 年 9 月站点埋点,30 天滚动窗口,已剔除爬虫与内部 IP);登录后的工作台、订单后台、内部报表不列入。全站 SSR 会把渲染算力、缓存一致性、Node 侧故障域一次性引进来,而后台页面多一跳服务端渲染,首屏反而更长。
可验证的收益只有三条:首字节 HTML 含正文、索引延迟由不可控变为发布后一小时可控、社交抓取器能读到 og:image。性能收益由缓存策略决定,与是否启用 SSR 没有直接关系——同一批页面两种缓存配置,LCP 相差 1.4 秒。
版本基线:Nuxt 4.0 于 2025 年 7 月 15 日 GA,截至 2026 年 11 月最新 4.6.4;nuxt@4.6.4 的 engines 要求 Node ^22.22.3 || ^24.15.0 || >=26.0.0,选镜像阶段就要锁定,别留到部署。
核心概念
四种渲染方式:现做、预制、回锅
SSR(server-side rendering,服务端渲染)是每次请求在服务端拼 HTML。预渲染(prerender)是构建时把 HTML 生成成静态文件。ISR(incremental static regeneration,增量静态再生)是静态文件过期后,下一个请求触发后台重新生成。SWR(stale-while-revalidate,先用旧再更新)先返回旧内容,同时后台刷新。
类比:SSR 是现点现做,预渲染是预制菜,ISR 与 SWR 是预制菜放久了自动回锅。
反例是以为 ISR 和 SWR 有本质差别。它们的缓存行为相同,差别只在能否写入 CDN——截至 2026 年 11 月,isr 仅在 Netlify 与 Vercel 上追加 CDN 缓存层,自建 node-server 部署不会自动获得分布式缓存。把它当自建 Node 集群的缓存方案,会得到 TTL 语义却不带共享存储。
routeRules:按路径前缀声明渲染方式
routeRules 是 nuxt.config.ts 里按路径声明渲染方式的配置,一条规则决定一组 URL 走 SSR、预渲染、ISR、SWR 还是 ssr: false。分档规则要先于技术选型定下来,图 10-1 是决策路径,顺序即优先级。
图 10-1 渲染方式的决策路径,先问是否要索引,再问是否随登录态变化
反例是全站开 SSR。后台页面本来不需要被索引,多一跳服务端渲染只是把 Node 变成瓶颈。
水合:接管已有 DOM 的前提是两次结果一致
服务端吐出的 HTML 在浏览器里被 Vue 接管,Vue 复用现有 DOM 并挂上事件监听,这个过程叫水合(hydration)。像服务端砌好了墙,客户端来装电线和开关,墙的位置必须和图纸一致,否则只能砸了重砌。
反例是模板里用 Date.now()、window.innerWidth 或随机数。服务端算一次、客户端再算一次,两次结果不同就水合不匹配,Vue 丢弃服务端 DOM 整棵重渲染,首屏的工作全废。
payload:随页面附上的数据包
服务端取到的数据要传给客户端,Nuxt 把它序列化进 HTML 里的 __NUXT_DATA__,页面源码里能看到这一坨 JSON。它像随菜附赠的调料包,不够可以补,太多就是负担——超过 100 KB 时,传输成本会吃掉 SSR 的收益。
反例是把整个接口响应塞进 payload。控制手段有三种:pick 只取渲染必需字段,transform 在服务端裁剪结构,4.6 新增的 serialize: false 把指定数据排除在 payload 之外。三种都有代价:pick 之后客户端拿不到未列入的字段,二次导航要重新请求;serialize: false 的字段在客户端是 undefined,使用处必须兜底。
动手实践
第一步:把分档写进 routeRules
| 页面类型 | 渲染方式 | 首屏 HTML | 数据新鲜度 | 主要代价 |
|---|---|---|---|---|
| 营销页、文档、博客详情 | prerender 或 isr | 完整 | 发布级 | 构建时长、失效流程 |
| 商品列表与详情(非个性化) | swr 600 s | 完整 | 十分钟级 | 命中率依赖共享存储 |
| 搜索、登录态价格 | SSR,禁缓存 | 完整 | 实时 | Node 算力、下游压力 |
| 工作台、后台 | ssr: false | 空壳 | 实时 | 无 SEO 收益 |
| 帮助中心长尾 URL | prerender + 按需再生成 | 完整 | 天级 | 构建与存储成本 |
// nuxt.config.ts —— Nuxt 4.6.x
export default defineNuxtConfig({
compatibilityDate: '2026-11-01',
routeRules: {
'/': { prerender: true },
'/blog/**': { isr: 3600 },
'/products/**': { swr: 600 },
'/admin/**': { ssr: false },
'/old-pricing': { redirect: { to: '/pricing', statusCode: 301 } },
},
})预期输出:nuxt build 后 .output/public 下出现 /index.html;访问 /admin/users 返回的 HTML 是空壳,正文在客户端补齐;访问 /old-pricing 直接 301 到 /pricing。
两处细节要留意。TTL 的依据是业务可接受的陈旧时间:博客取 3600 秒,因为作者改稿后能接受一小时生效;商品价取 600 秒,因为活动价按十分钟同步。业务无法接受陈旧时,正确做法是发布时主动失效,而不是把 TTL 压到 5 秒——那只是在缓存层之上再加一层延迟。另外,routeRules 里的 redirect 与 proxy 在 server middleware 之前执行,部分托管平台会直接处理,所以不能拿它当鉴权手段。
第二步:让首屏 HTML 自己带正文
<!-- app/pages/blog/[slug].vue —— Nuxt 4.6.x -->
<script setup lang="ts">
const route = useRoute()
const key = computed(() => `post:${route.params.slug}`)
const { data: post, error } = await useAsyncData(
key,
(_nuxtApp, { signal }) => $fetch(`/api/posts/${route.params.slug}`, { signal }),
{
pick: ['title', 'html', 'updatedAt'],
getCachedData: (k, nuxtApp) => nuxtApp.payload.data[k] ?? nuxtApp.static.data[k],
},
)
if (error.value) {
throw createError({ statusCode: 404, statusMessage: '文章不存在', fatal: true })
}
useSeoMeta({ title: () => post.value?.title, ogType: 'article' })
</script>运行结果:访问一个不存在的 slug,响应状态码是 404 而不是 200;访问存在的 slug,view-source 里能看到文章正文;useSeoMeta 生成的 <title> 与 og:type 出现在 head 里,抓取器不执行 JS 也能读到。
三条约束要写进编码规范。第一,错误分支必须 throw createError,只在模板写 v-if="!post" 时 HTTP 状态仍是 200,这是 SPA 迁移最常见的验收失败项。第二,服务端渲染期间组件内的 $fetch 不携带当前请求的 Cookie,鉴权数据要走 useFetch 或显式包一层 useRequestFetch,否则会出现服务端渲染成未登录、水合后切回登录态的闪烁。第三,任何依赖运行环境的值(时区、window 尺寸、随机数)不得进入服务端渲染输出。
useAsyncData 的默认值同样影响结果:deep 默认 false,直接改写 data.value.nested.x 不触发更新;dedupe 默认 'cancel',同 key 并发请求会中止旧请求;同一 key 的多个调用必须让 handler、deep、transform、pick、getCachedData、default 保持一致,否则生产上两个组件会取到不同的数据。
第三步:三条命令验收
curl -sI https://example.com/products/1001 | head -1 # 预期 HTTP/2 200
curl -sI https://example.com/products/999999 | head -1 # 预期 HTTP/2 404
curl -s https://example.com/blog/hello | grep -c '正文关键词' # 预期 1预期输出依次为 HTTP/2 200、HTTP/2 404、1。这三行附在发布单上,比"点开看看"可靠。验收按四组拆:状态码、正文可达、meta 完整、payload 体积,四组各自抽查,不合并成一次目视。
预渲染有个只有真跑过才会遇到的细节:prerender 在构建期会真的执行页面里的 useAsyncData,构建机连不上接口时 nuxt build 直接失败,而不是降级成空页。把构建期数据源改成只读快照库,并在 CI 里对 /api/* 做本地 stub,构建时间会从 6 分 40 秒涨到 11 分 20 秒,这笔成本要写进流水线预算。
常见误解
其一,以为 isr 等于分布式缓存。Nitro 的 cache 存储默认落在进程内存,多副本部署下各 Pod 独立缓存,命中率随副本数下降;发版后缓存全冷,首波流量按副本数倍回源上游。可选路径有两条:把缓存推到 CDN 或反向代理,让 Node 只负责回源;或显式配置 nitro.storage.cache 指向 Redis 与共享文件系统。
其二,以为页面用了 useAsyncData 就一定渲染出正文。deep、dedupe、同 key 一致性这些默认值都会影响最终结果,而且它们不报错。排查时按下面这张表对现象找根因:
| 现象 | 根因 | 处理 |
|---|---|---|
| 缺失资源仍返回 200 | 只用模板条件渲染,没抛错 | 统一 throw createError |
| 服务端渲染成未登录、水合后闪一下变登录态 | 组件内 $fetch 不带 Cookie | 改用 useFetch 或包 useRequestFetch |
| 首屏白闪后整页重渲染 | 模板里用时区、随机数、window | 环境相关值移到 onMounted 或 <ClientOnly> |
| 发版后上游压力激增 | 缓存全冷、TTL 集中过期 | 缓存改共享存储,发版前预热 Top 2000 URL |
| 构建在 CI 上突然失败 | 预渲染页面调了未 stub 的接口 | 构建期快照库 + 接口 stub |
其三,以为 Nuxt 5 的迁移可以先放一放。截至 2026 年 11 月 Nuxt 5 仍处于开发阶段,没有稳定版;future.compatibilityVersion: 5 可以在 4.2 以上版本提前验证,但要不要纳入一期得单独决策。另外,上线后"索引延迟中位数 ≤ 1 天"目前只是目标值,需要在 30 天观察期复核,别提前写进汇报。
小结
《测试与质量:Vitest 组件测试与 Playwright E2E》让改动有门禁,这一章让首屏有内容。五条要点:
- 迁移的验收对象是 HTML 本身:关掉 JS 还能看到正文,缺失资源返回 404。写成"用了 SSR"等于什么都没验收。
- 渲染方式按"是否要索引 → 是否随登录态变化 → 数据变更频率"三问定档,全部收敛到
routeRules。 isr与swr缓存行为相同,差别在能否写入 CDN;自建node-server要自己配共享存储,否则多副本命中率打折。- 服务端渲染期间
$fetch不带 Cookie、环境相关值不能进输出、错误必须抛出来——这三条不写成规范,验收一定失败。 - payload 超过 100 KB 收益就被传输吃掉,
pick、transform、serialize: false各有代价,选之前先确认客户端是否还要这些字段。
相关主题
单仓单应用的构建、性能与渲染都走通了,下一个问题是应用变多之后怎么办:十二个应用共用一套插件,每改一行都要全量重建。《进阶:Monorepo 与组件库发布》用 pnpm workspace 与 Turborepo 处理这类多包仓库的依赖提升、任务编排与增量构建。