加载与错误

NuxtLoadingIndicator

页面切换时显示顶部加载进度条，提升用户对导航状态的感知。

<!-- app/app.vue -->
<template>
  <NuxtLoadingIndicator />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

Props

Prop	类型	默认值	说明
color	string	#00DC82	进度条颜色
height	number	3	进度条高度(px)
duration	number	2000	最大持续时间(ms)
throttle	number	200	节流时间(ms)，快速导航不显示
estimatedProgress	function	-	自定义进度计算函数

自定义样式

<template>
  <NuxtLoadingIndicator
    color="#3B82F6"
    :height="4"
    :duration="3000"
    :throttle="100"
  />
</template>

配合深色模式

<template>
  <NuxtLoadingIndicator :color="isDark ? '#60A5FA' : '#3B82F6'" />
</template>

<script setup>
const colorMode = useColorMode()
const isDark = computed(() => colorMode.value === 'dark')
</script>

自定义进度函数

<NuxtLoadingIndicator
  :estimated-progress="(duration, elapsed) => {
    // 快速开始，缓慢接近 100%
    const progress = elapsed / duration
    return Math.min(100, progress < 0.5
      ? 2 * progress * 100
      : (1 - Math.pow(2, -10 * progress)) * 100
    )
  }"
/>

TIP

throttle 参数可以避免快速导航时进度条闪烁 默认 200ms 内完成的导航不会显示进度条

---

NuxtErrorBoundary

捕获子组件的运行时错误，防止整个页面崩溃，类似于 React 的 ErrorBoundary。

<template>
  <NuxtErrorBoundary @error="handleError">
    <UnstableComponent />

    <template #error="{ error, clearError }">
      <div class="error-fallback">
        <p>组件加载失败</p>
        <p>{{ error.message }}</p>
        <button @click="clearError">重试</button>
      </div>
    </template>
  </NuxtErrorBoundary>
</template>

<script setup>
function handleError(error) {
  console.error('组件错误:', error)
  // 上报错误到监控服务
  reportError(error)
}
</script>

错误边界 vs 全局错误处理

特性	NuxtErrorBoundary	全局错误页面
作用范围	包裹的子组件	整个应用
用户体验	局部 fallback	全屏错误页
页面状态	其余部分正常	整页不可用
适用场景	第三方组件、实验性功能	致命错误

实际应用：保护第三方组件

<template>
  <div>
    <h1>数据分析</h1>

    <!-- 核心内容不需要错误边界 -->
    <DataSummary :data="summaryData" />

    <!-- 第三方图表可能有兼容性问题 -->
    <NuxtErrorBoundary>
      <ComplexChart :data="chartData" />
      <template #error="{ error, clearError }">
        <div class="chart-fallback">
          <p>图表加载失败</p>
          <button @click="clearError">重试</button>
        </div>
      </template>
    </NuxtErrorBoundary>
  </div>
</template>

---

NuxtClientFallback

客户端回退组件，SSR 时正常渲染子组件，客户端 Hydration 失败时显示 fallback。

<template>
  <!-- 文本 fallback -->
  <NuxtClientFallback fallback="加载失败">
    <BrowserOnlyComponent />
  </NuxtClientFallback>

  <!-- 插槽 fallback -->
  <NuxtClientFallback>
    <InteractiveMap :center="center" />
    <template #fallback>
      <div class="map-fallback">
        <p>地图加载失败</p>
        <a href="/contact">联系客服</a>
      </div>
    </template>
  </NuxtClientFallback>
</template>

Props

Prop	类型	默认值	说明
fallback	string	-	fallback 文本
hydrate	boolean	true	是否参与 Hydration
hydrateAfter	number	-	Hydration 延迟(ms)
lazy	boolean	false	懒加载 Hydration

NuxtClientFallback vs ClientOnly

特性	NuxtClientFallback	ClientOnly
SSR 渲染	✅ 尝试渲染子组件	❌ 只渲染 fallback
客户端失败时	显示 fallback	显示子组件
适合场景	子组件可能失败	子组件确定不支持 SSR

TIP

选择建议：如果子组件支持 SSR 但客户端可能失败 用 <NuxtClientFallback>；如果子组件完全不支持 SSR，用 <ClientOnly>