Nuxt 文章详情切换卡顿:lazy 数据与骨架屏

2026-11-19 前端开发 有希 40 views

文章列表点进详情,旧页面停住不动,过一会儿才整页换掉;换成骨架屏后,标题、目录和代码高亮又可能晚一拍。根因通常不是渲染慢,而是详情页在 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 首屏不一致排查,更多记录在 前端开发。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles