Nuxt 文章详情切换卡顿:lazy 数据与骨架屏
文章列表点进详情,旧页面停住不动,过一会儿才整页换掉;换成骨架屏后,标题、目录和代码高亮又可能晚一拍。根因通常不是渲染慢,而是详情页在 setup 里 await 了数据,路由切换被阻塞。把数据改成懒加载只是第一步,后面还有四件事要一起改。
卡顿发生在导航阶段,不在渲染阶段
常见写法是这样:
const { data: article } = await useAsyncData(
() => `article-${id.value}`,
() => fetchArticle(id.value),
{ watch: [id] },
)
setup 里的 await 会让这次路由导航等到数据返回。SPA 切换时,浏览器不会先渲染新页面的空壳,而是一直保留旧页面,直到新页面的 setup 完成。用户看到的就是“点了没反应”,网络慢时尤其明显。
NuxtLoadingIndicator 能补一点反馈,但它只说明导航开始了,不能解决旧页面停留。真正的分界是:谁在等数据,以及等的时候渲染什么。
lazy 改变的是“谁在等”
把 lazy 打开:
const { data: article, error, status } = await useAsyncData(
() => `article-${id.value}`,
() => fetchArticle(id.value),
{ watch: [id], lazy: true },
)
客户端导航不再等这个 Promise,路由先进入新页面,article 先是 null,数据回来后再触发更新。服务端渲染仍然会等数据落定再输出 HTML,所以首屏和搜索引擎拿到的还是完整正文。这一点很关键:lazy 优化的是客户端切换,不是把 SSR 也改成空壳。
useAsyncData 的 key 必须把文章标识和语言一起带上。否则从 A 文章切到 B 文章时,旧 key 的缓存会被复用,页面先显示上一篇内容,再被新请求覆盖。watch 只负责重新取数,不负责隔离缓存,两者要一起写对。数据没到时要先渲染骨架:
<template>
<article>
<div v-if="!post" class="animate-pulse" aria-busy="true">
<span class="sr-only">正在加载文章</span>
<div class="h-8 w-11/12 rounded bg-gray-200" />
<div class="mt-3 h-8 w-3/5 rounded bg-gray-200" />
<div class="mt-6 h-36 rounded-lg bg-gray-200" />
</div>
<template v-else>
<h1 v-text="post.title" />
<div v-html="post.content" />
</template>
</article>
</template>
骨架的结构要和真实页面对齐:标题两行、元信息一行、标签一行、正文段落、代码块。只放一个居中转圈也能用,但数据到位后整页高度突然变化,视觉上比等待更难受。aria-busy 和隐藏的“正在加载”文本则负责读屏反馈。
客户端错误处理不能继续写在 setup 里
原来在 setup 里直接判断错误是安全的,因为数据已经 awaited。改成 lazy 后,客户端第一次执行 setup 时 status 还是 pending,error 也是空的;如果继续写 if (error.value) throw,它要么不触发,要么在错误的时机抛。
正确做法是等状态变化:
function handleLoadState() {
if (status.value === 'error') {
const notFound = isNotFoundError(error.value)
if (import.meta.server) {
if (notFound)
throw createError({ statusCode: 404, fatal: true })
throw createError({ statusCode: 500, statusMessage: '文章加载失败', fatal: true })
}
showError(createError({
statusCode: notFound ? 404 : 500,
message: notFound ? '文章不存在' : '文章加载失败',
fatal: true,
}))
return
}
if (status.value === 'success' && !article.value) {
if (import.meta.server)
throw createError({ statusCode: 404, fatal: true })
showError(createError({ statusCode: 404, message: '文章不存在', fatal: true }))
}
}
handleLoadState()
watch(status, handleLoadState)
status 会在 idle、pending、success、error 之间变化。上面这段只在 error 或“成功但没有数据”时处理,pending 阶段什么都不做,骨架屏继续显示。服务端仍然要抛 createError,这样 404 页面和响应状态码才是对的;客户端则用 showError,因为它是在数据落定后才执行,不能在 setup 同步阶段抛。
如果错误处理写成 watch(error, ...),要注意请求重试时 error 可能先被清空再赋值,容易重复弹错。监听 status 更稳,它表示的是这次请求的整体状态,而不是单个字段的瞬时值。
SEO 元数据要能跟着数据晚到
lazy 之后,客户端首帧的 post 是 null。如果 SEO 元数据在 setup 里按值传入:
useSeoMeta({
title: post.value?.title,
description: post.value?.summary,
})
首帧拿到的就是空字符串,数据回来后也不会自动更新。应改成 getter 或 computed:
const fallbackTitle = '技术文章'
useSeoMeta({
title: () => post.value?.seoTitle || post.value?.title || fallbackTitle,
description: () => post.value?.seoDescription || post.value?.summary,
})
结构化数据同理,只有文章存在时才输出:
useHead({
script: computed(() => {
const item = post.value
if (!item)
return []
return [{
type: 'application/ld+json',
innerHTML: JSON.stringify({
'@context': 'https://schema.org',
'@type': 'BlogPosting',
headline: item.title,
datePublished: item.publishTime,
mainEntityOfPage: `${siteUrl}/blog/${item.slug || item.id}`,
}),
}]
}),
})
canonical 最好只依赖路由参数,不依赖异步文章对象。否则数据没到时用 id 拼一个,数据到了再换成 slug,搜索引擎会看到两个不同地址。路由本身已经能确定文章标识,就不要让 canonical 跟着网络请求摆动。
目录与代码高亮:正文晚到后的二次初始化
标题目录通常是 onMounted 时扫描正文里的 h2/h3。lazy 之后,onMounted 执行时正文还没进来,目录自然是空的。用固定 setTimeout 补偿也不可靠:网络快时浪费,慢时不够。
更稳的是监听正文容器:
let timer: ReturnType<typeof setTimeout> | null = null
let observer: MutationObserver | null = null
function scheduleExtract() {
if (timer)
clearTimeout(timer)
timer = setTimeout(() => {
timer = null
extractHeadings()
}, 80)
}
function observeProse() {
observer?.disconnect()
const target = document.querySelector('article')
if (!target)
return
observer = new MutationObserver(scheduleExtract)
observer.observe(target, { childList: true, subtree: true })
}
onMounted(() => {
extractHeadings()
observeProse()
})
onUnmounted(() => {
observer?.disconnect()
if (timer)
clearTimeout(timer)
})
watch(() => route.fullPath, () => nextTick(observeProse))
80ms 的防抖是为了合并一次渲染里的多次 DOM 变更;路由切换后正文容器可能被替换,所以还要重新绑定观察目标。
代码高亮还有另一类问题:MDC 默认会为每个代码块请求一次高亮接口,并把主题 JSON 放进 query。长文有十几个代码块时,单个 URL 很容易超过网关的 8KB 上限,直接返回 414。请求失败后才回退到浏览器本地高亮,等于先白跑一轮失败请求。
如果项目使用 shiki 的浏览器端高亮,可以在客户端插件里提前置位模块开关:
export default defineNuxtPlugin(() => {
try {
sessionStorage.setItem('mdc-shiki-highlighter', 'browser')
} catch {
// 隐私模式下 sessionStorage 不可用,保持默认行为
}
})
这个插件只在客户端执行,写入的是当前标签页的 sessionStorage,不会改变服务端渲染结果;服务端仍然用同一份高亮产物。它也不负责加载 shiki 本体,只是把高亮模块的分支提前切到浏览器实现。代码块格式和预览可以用 Markdown 预览 快速核对。
判断是否需要这段兜底,直接看 devtools 的请求列表:长文加载时如果出现多条 _mdc/highlight 请求,而且状态是 414,就说明主题 JSON 进了 query;如果没有请求、直接出现高亮结果,说明已经走本地。两次请求都失败时,保留纯文本代码块也能读,不要让高亮错误阻断正文渲染。
一张排查表
| 现象 | 根因 | 处理 |
|---|---|---|
| 点击后旧页面停住 | setup 里 await 数据 | 加 lazy: true,先渲染骨架 |
| 骨架一直不消失 | 错误分支只写了 throw | 监听 status,客户端用 showError |
| 标题和 description 为空 | SEO 元数据按值传入 | 改成 getter / computed |
| 切换文章后目录不更新 | 只在 onMounted 扫描一次 | MutationObserver + 路由切换重绑 |
| 代码高亮先失败后成功 | 高亮请求 URL 超限 | 客户端改用本地 shiki |
| 404 页面状态码不对 | 客户端抛错代替 SSR 抛错 | 服务端 throw,客户端 showError |
常见问题
lazy: true 后 SSR 还会等数据吗? 会。服务端仍会等数据落定再输出 HTML,lazy 主要影响客户端导航。
为什么骨架屏出现了,标题却是空的? SEO 元数据在首帧按值读取了 null。改成函数或 computed,让数据回来后重新计算。
为什么目录在切换文章后不更新? 异步正文插入 DOM 晚于 onMounted。监听正文容器的变化,并在路由切换后重新绑定。
所有 useAsyncData 都应该加 lazy 吗? 不需要。首屏必须完整输出的内容、决定页面是否存在的关键数据,继续保持阻塞更简单;只有“可以让用户先看到页面框架”的详情数据适合懒加载。
代码高亮为什么先失败再成功? 默认高亮请求把主题 JSON 放在 query 里,长文超过网关 URI 上限后返回 414,再回退本地。提前切到本地高亮可以省掉这一轮。
lazy 不是单个配置项,而是把页面从“数据就绪才渲染”改成“先渲染框架、再补数据”。错误处理、SEO、目录和代码高亮都属于“补数据之后”的工作,少改一处就会留下新的空白或卡顿。SSR 与客户端首帧的其他差异可以继续看 Nuxt 首屏不一致排查,更多记录在 前端开发。
評論
還沒有評論,來說兩句吧