本文详解如何在 nuxt 3 中可靠地判断页面初始化阶段的所有异步操作（包括 api 请求、服务端预取数据及静态资源加载）是否真正完成，并据此控制自定义加载页的显隐，避免过早隐藏导致内容闪烁或资源未就绪问题。
本文详解如何在 nuxt 3 中可靠地判断页面初始化阶段的所有异步操作（包括 api 请求、服务端预取数据及静态资源加载）是否真正完成，并据此控制自定义加载页的显隐，避免过早隐藏导致内容闪烁或资源未就绪问题。
在 Nuxt 3 中实现「全局加载页」看似简单，但若仅依赖 page:start / page:finish 钩子（如常见示例），极易陷入加载态提前关闭的陷阱——因为 page:finish 仅表示 Vue 组件挂载和路由过渡完成，并不保证：
- useAsyncData 或 useFetch 的数据已响应并解析完毕；
- 服务端渲染（SSR）中 asyncData 的预取已完成且客户端已同步；
- 关键静态资源（如字体、关键 CSS、内联图像）已加载就绪；
- 第三方库（如图表库、地图 SDK）的异步初始化已完成。
因此，以下写法存在根本性缺陷：
<script setup>
const nuxtApp = useNuxtApp()
const loading = ref(true)
nuxtApp.hook('page:start', () => { loading.value = true })
nuxtApp.hook('page:finish', () => { loading.value = false }) // ❌ 不可靠：非“全部完成”信号
</script>✅ 正确方案：组合式等待策略
Nuxt 3 官方推荐采用 onNuxtReady + onBeforeMount + 数据加载守卫 的组合方式，确保加载状态覆盖完整生命周期：
1. 使用 onNuxtReady 确保框架就绪
该钩子在 Nuxt 应用完全初始化（含所有插件、路由、状态同步）后触发，是加载页可安全关闭的最早可靠时机之一：
<script setup lang="ts">
import { onNuxtReady } from '#app'
import { ref, onBeforeMount } from 'vue'
const loading = ref(true)
// 等待 Nuxt 框架完全就绪（含 SSR 数据 hydration 完成）
onNuxtReady(() => {
loading.value = false
})
// （可选增强）确保 DOM 已准备就绪再关闭加载页
onBeforeMount(() => {
// 可在此处补充关键资源检查逻辑（见下文）
})
</script>2. 主动等待关键异步数据（推荐）
若页面依赖 useAsyncData，应显式等待其完成，而非依赖全局钩子：
<script setup lang="ts">
import { useAsyncData } from '#app'
import { ref, onMounted } from 'vue'
const loading = ref(true)
const { data, pending } = useAsyncData('posts', () => $fetch('/api/posts'))
// 在组件挂载时监听数据状态变化
onMounted(() => {
const stop = watch(pending, (isPending) => {
if (!isPending && data.value) {
loading.value = false
stop() // 停止监听，避免重复触发
}
})
})
</script>3. 静态资源加载兜底检测（进阶）
对于关键静态资源（如字体、核心 CSS），可结合 document.fonts.load() 或 link.onload 手动监听：
// utils/resource-guard.ts
export function waitForCriticalResources(): Promise<void> {
return Promise.all([
document.fonts.load('1em "Inter"'),
new Promise(resolve => {
const link = document.querySelector('link[href*="main.css"]') as HTMLLinkElement
if (link && link.sheet) resolve()
else link?.addEventListener('load', resolve)
})
]).then(() => {})
}并在 onNuxtReady 后调用：
onNuxtReady(async () => {
await waitForCriticalResources()
loading.value = false
})⚠️ 注意事项与最佳实践
- 避免滥用 page:finish：它本质是路由导航钩子，与资源加载无直接关联，不应作为加载结束依据；
- SSR/CSR 一致性：onNuxtReady 在服务端不执行，在客户端确保 hydration 完成后触发，天然适配 SSR 场景；
- 性能权衡：过度等待（如监听所有图片 load 事件）会延迟首屏可见时间，建议仅监控阻塞渲染的关键资源；
- 用户体验优化：可设置最小加载时长（如 setTimeout(..., 300)），防止加载态一闪而过影响感知。
通过上述组合策略，你将获得一个真正可靠的加载控制机制——既不过早隐藏遮罩导致内容跳变，也不过度等待损害性能，完美契合现代 Nuxt 3 应用的工程化需求。
