本文详解在 Nuxt 3 中实现「真正完成态」加载遮罩的正确方式：不仅监听路由切换钩子，更需结合客户端资源加载、服务端数据获取及静态资产就绪时机，避免过早隐藏加载页导致内容闪烁或样式错乱。
本文详解在 nuxt 3 中实现「真正完成态」加载遮罩的正确方式：不仅监听路由切换钩子，不仅监听路由切换钩子，更需结合客户端资源加载、服务端数据获取及静态资产就绪时机，避免过早隐藏加载页导致内容闪烁或样式错乱。
在 Nuxt 3 中，仅依赖 page:start 和 page:finish 钩子（如问题中所用）无法准确反映所有请求与静态资源的加载完成状态。原因在于：
- page:finish 仅表示 Vue 页面组件已挂载完毕，不保证 useAsyncData、useFetch 等异步数据已返回；
- 它完全忽略静态资源（如 <img>、CSS 字体、第三方库脚本）的加载状态；
- 在 SSR 场景下，服务端预取的数据已注入客户端，但客户端仍可能触发重复请求（如未设置 server: false），此时 page:finish 并不等待这些请求。
✅ 正确方案需分层控制，兼顾 服务端数据就绪 + 客户端资源加载 + 路由生命周期：
1. 优先使用 useNuxtApp().hook('app:mounted') 替代 page:finish
app:mounted 是客户端应用完全挂载、所有组合式 API（包括 useAsyncData 的响应式数据）已就绪的可靠信号：
<template>
<div v-if="loading" class="fixed inset-0 z-50 bg-white flex items-center justify-center">
<div class="text-xl font-medium text-gray-700">Loading...</div>
</div>
<NuxtPage v-else />
</template>
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useNuxtApp } from '#imports'
const nuxtApp = useNuxtApp()
const loading = ref(true)
// ✅ 推荐：等待整个应用挂载完成（含所有 useAsyncData 响应）
nuxtApp.hook('app:mounted', () => {
loading.value = false
})
// ⚠️ 补充：若需兼容 SSR 首屏渲染后立即隐藏（如纯静态页），可加此逻辑
onMounted(() => {
// 防止 SSR 水合后短暂闪现 loading
if (loading.value && document.readyState === 'complete') {
loading.value = false
}
})
</script>2. 主动监听关键静态资源加载（按需增强）
若页面含大量关键图片、字体或外部 JS（如地图 SDK），建议显式监听其加载完成：
// utils/loadResource.ts
export function waitForImages(selector: string = 'img[data-loaded="false"]'): Promise<void> {
return new Promise((resolve) => {
const imgs = Array.from(document.querySelectorAll(selector)) as HTMLImageElement[]
if (imgs.length === 0) return resolve()
let loadedCount = 0
const checkDone = () => {
if (++loadedCount >= imgs.length) resolve()
}
imgs.forEach(img => {
if (img.complete) {
checkDone()
} else {
img.addEventListener('load', checkDone)
img.addEventListener('error', checkDone) // 错误也视为“完成”
}
})
})
}在 app:mounted 后调用：
nuxtApp.hook('app:mounted', async () => {
await waitForImages('img[loading="eager"]') // 仅监听关键图
loading.value = false
})3. 注意事项与最佳实践
- ❌ 不要仅依赖 page:start/page:finish 实现加载态 —— 它们语义是「路由导航阶段」，非「资源就绪阶段」；
- ✅ 若使用 useAsyncData，确保设置 immediate: true（默认）且未禁用客户端获取（server: false 会跳过服务端预取，增加客户端请求）；
- ✅ 在 app.vue 中统一管理加载状态，避免各页面重复实现；
- ✅ 对于 PWA 或离线场景，可结合 window.addEventListener('load', ...) 监听 document 及所有资源（含 CSS、字体），但注意该事件可能晚于首屏渲染，需权衡 UX；
- ? 如需支持「局部加载」（如按钮点击后显示加载），应使用独立状态，而非全局 loading。
综上，app:mounted 是 Nuxt 3 中最接近「所有请求与初始化完成」的可靠钩子；配合资源级监听，即可构建稳定、无闪烁的自定义加载体验。
