Nuxt 4 页面首屏和浏览器显示不一致怎么排查

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

服务端发下来的 HTML 里有 6 个工具标签,浏览器接管后变成 4 个;或者时间块先空白、再突然出现。这类问题不是缓存,也不是接口慢,而是服务端和浏览器的第一次渲染用了不同的值。本文以门户的工具子导航、cron 和 TOTP 页面为例,说明差异从哪来、怎么复现、怎么改。

现象:第一次渲染和第二次渲染不是同一份 DOM

Nuxt 会先在服务端把页面渲染成 HTML,浏览器拿到后再由 Vue 接管。两边只要有一个值不同,开发环境就会出现首帧不一致的警告;生产环境通常不打印警告,但会丢弃服务端 HTML 重新渲染,表现为闪烁、布局跳动或事件绑定错位。

现象常见来源
标签数量、列数在接管后变化首帧读了 window.innerWidth、matchMedia
时间、倒计时、下次执行时间先空后有首帧读了 Date.now() 或本地时区
“最近使用”第一次为空,刷新后又出现首帧读了 localStorage
二维码、画布区域一直空白ClientOnly 的 ref 在父组件挂载时还是 null
随机颜色、随机 id 两边不同渲染期间调用了 Math.random() 或 crypto.randomUUID()

这些值有一个共同点:服务端要么没有,要么和浏览器不一样。把它们放进首次渲染,服务端和客户端就必然对不上。

最小复现:让首帧依赖视口

下面这段写法在浏览器里看起来没问题,但服务端没有 window,只能走默认分支;浏览器如果命中窄屏分支,首帧的标签数量就和服务端不同。

const visibleCount = ref(
  import.meta.client && window.innerWidth < 1200 ? 4 : 6
)

服务端渲染 6 个,浏览器首次渲染 4 个,Vue 接管时就会发现结构不一致。开发环境控制台会出现类似 Hydration completed but contains mismatches 或节点数量不一致的警告。

更隐蔽的是时间。cron 页面在服务端不能计算“接下来 5 次执行”,因为服务端的当前时间和用户浏览器可能差几秒,直接渲染会得到不同文本。门户的做法是首帧不渲染这块内容:

const ready = ref(false)
const nowMs = ref(0)

onMounted(() => {
  nowMs.value = Date.now()
  ready.value = true
})

模板里用 v-if="ready && analysis.ok" 包住执行时间列表。这样服务端只输出表单和说明,浏览器挂载后再补时间块,两端首帧的 DOM 是一致的。

根因:三类值不能进首帧

1. 视口和媒体查询

window.innerWidth、matchMedia、ResizeObserver 都只有浏览器才有。服务端没有真实视口,只能猜一个默认值。只要这个默认值和浏览器首次计算的结果不同,标签数量、列数、是否显示侧栏就会对不上。

门户的 ToolNav 把 visibleCount 的初值固定为常量 6,服务端和浏览器都先渲染 6 个;挂载后再用 scrollWidth > clientWidth + 1 判断是否溢出,逐级减少,并用 ResizeObserver 在窗口变化时重算。初值不读视口,是这段代码能稳定渲染的前提。

2. 时间和时区

Date.now()、new Date()、Intl.DateTimeFormat 的结果依赖运行环境。服务端可能用 UTC,用户浏览器用本地时区;即使同一时区,两次执行也差几十毫秒。把“现在”直接写进模板,服务端和客户端很难完全一致。

cron、TOTP、时间戳转换都采用“先渲染静态结构,挂载后再算”的方式。TOTP 的口令在 ready 之前恒为空字符串,进度条和 otpauth 链接也不输出,避免服务端生成一个几秒后就过期的验证码。

3. 浏览器存储和随机值

localStorage、sessionStorage、navigator.userAgent、Math.random()、crypto.randomUUID() 都属于这一类。服务端没有存储,随机值也无法复现。门户的“最近使用工具”首屏恒为空数组,挂载后才从 localStorage 读取;ua 工具页也是在客户端才读 navigator.userAgent。

随机值还有一个容易忽略的位置:列表 key。如果在渲染时生成随机 key,服务端和客户端各生成一次,Vue 会认为节点对不上。key 应该用稳定的业务 id,而不是随机数。

4. ClientOnly 的 ref 不是“挂载就有”

ClientOnly 只保证插槽在客户端渲染,不保证父组件的 onMounted 执行时插槽已经存在。二维码美化页曾经在父组件 onMounted 里直接拿 canvasHost.value,当时还是 null,append 被静默跳过,页面一直空白,也没有报错。

现在的写法是监听 ref 本身:

watch(canvasHost, el => {
  if (el) appendCanvas(el)
}, { immediate: true })

元素什么时候出现,什么时候执行,不依赖父组件的挂载时机。

修复:首帧用常量,差异留到挂载后

场景推荐写法不要做
标签数量、列数初值用常量,onMounted 测量后调整在 setup 里读 innerWidth
时间、倒计时ready 门控,挂载后再算在模板里直接 Date.now()
本地存储首帧空数组,onMounted 读取在 setup 同步读 localStorage
纯客户端组件ClientOnly + 固定占位尺寸父组件 onMounted 直接拿插槽 ref
随机值用稳定 id 或挂载后生成渲染期间 Math.random()

如果一块内容确实只对浏览器有意义,比如画布、扫码、定位,用 ClientOnly 包起来是合理的。但要给它一个固定的占位高度,否则服务端 HTML 没有这块,浏览器接管后页面会突然变高,体验上仍然像“跳了一下”。

验证:对比服务端 HTML 和浏览器 DOM

先看服务端 HTML 里有没有不该出现的时间块:

curl -s 'http://[::1]:3001/toolkit/cron' | grep -c '接下来'

期望输出 0。如果输出大于 0,说明“接下来 N 次执行”被服务端渲染了,时间一变就可能不一致。

再看 TOTP 页面是否把口令写进了首屏:

curl -s 'http://[::1]:3001/toolkit/totp' | grep -c 'otpauth'

期望输出 0。口令和 otpauth 链接都应该在挂载后出现。

检查项期望结果说明
cron 首屏不含“接下来”时间块由 ready 门控
TOTP 首屏不含 otpauth口令挂载后生成
子导航首屏标签数量固定初值不读视口
浏览器控制台无首帧不一致警告开发环境最直观
生产构建无闪烁、无布局跳动生产不打印警告,需肉眼和 DOM 对比

生产环境不会像开发环境那样把警告打出来,所以不能只看控制台。更可靠的做法是:用 curl 拿到服务端 HTML,数一下关键节点;再用浏览器开发者工具看接管后的 DOM,两者结构应该一致。

边界与坑

不是所有差异都要消除。 画布、扫码、定位这类只有浏览器能做的功能,本来就不应该出现在服务端 HTML 里。用 ClientOnly 隔离,并给固定占位,是正确做法。

不要用 suppressHydrationWarning 掩盖结构差异。 它适合处理时间文本这类无法避免的小差异,不适合标签数量、列表长度这种结构问题。结构不一致时,Vue 仍然会重新渲染,事件和状态可能错位。

不要为了省事关闭 SSR。 内容页、工具说明页需要服务端 HTML 做收录和首屏展示。关闭 SSR 会把首屏不一致变成首屏空白,问题更大。

时区要显式约定。 服务端和浏览器都可能用本地时区。展示“北京时间”时,固定 utcOffset(8) 或明确写出时区,不要依赖运行环境的默认值。

第三方脚本也会改 DOM。 广告、统计、客服脚本如果在 Vue 接管前插入节点,也可能造成结构不一致。排查时先禁用第三方脚本,再对比首屏。

相关工具

用 cron 表达式解析工具 看“接下来 N 次执行”在页面上的实际渲染时机;这类时间块最适合验证 ready 门控是否生效。

TOTP 页面也是同一套思路:TOTP 验证码工具 在服务端只输出表单,口令和进度条都在挂载后生成。更多 Nuxt 排错记录放在 技术笔记。

FAQ

生产环境为什么没有首帧不一致的警告?

Vue 在生产构建里会去掉大部分开发警告。看不到警告不代表没有问题,通常表现为重新渲染、闪烁或事件错位。要在开发环境复现,或者对比服务端 HTML 和浏览器 DOM。

用了 ClientOnly 为什么还会闪?

ClientOnly 只保证内容在客户端渲染,不保证占位高度。服务端 HTML 里没有这块内容,浏览器接管后插入,页面就会变高。给占位容器一个固定高度或最小高度,可以消除布局跳动。

能不能用 process.client 判断?

可以判断当前代码在哪一端执行,但不能解决首帧不一致。服务端走一个分支、浏览器走另一个分支,首帧 DOM 仍然不同。正确做法是首帧用同一份常量,挂载后再更新。

时间显示一定要放到客户端吗?

如果时间只用于展示“当前时间”,可以放到客户端;如果是文章发布时间、固定时区的时间,可以在服务端格式化后输出,但要固定时区,避免服务端和浏览器各用一套默认值。

首帧不一致的排查顺序可以固定为:先看首帧有没有读视口、时间、存储或随机值;再把差异移到 onMounted;最后用服务端 HTML 和浏览器 DOM 对比确认。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles