---
title: "<NuxtClientFallback>"
description: "Nuxt 提供了 <NuxtClientFallback> 组件，当其子组件在 SSR 中触发错误时，该组件会改为在客户端渲染其内容"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/components/nuxt-client-fallback"
---
# \<NuxtClientFallback>

> Nuxt 提供了 \<NuxtClientFallback> 组件，当其子组件在 SSR 中触发错误时，该组件会改为在客户端渲染其内容

Nuxt 提供了 `<NuxtClientFallback>` 组件，当其子组件在 SSR（服务端渲染）中触发错误时，该组件会改为在客户端渲染其内容。

::note{to="https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/experimental-features#clientfallback"}
此组件处于实验阶段，要使用它，必须在 `nuxt.config` 中启用 `experimental.clientFallback` 选项。
::

```vue [pages/example.vue]
<template>
  <div>
    <Sidebar />
    <!-- 该组件将会在客户端渲染 -->
    <NuxtClientFallback fallback-tag="span">
      <Comments />
      <BrokeInSSR />
    </NuxtClientFallback>
  </div>
</template>
```

## 事件

- `@ssr-error`：当子组件在 SSR 中触发错误时发出该事件。注意该事件仅在服务端触发。
  ```vue
  <template>
    <NuxtClientFallback @ssr-error="logSomeError">
      <!-- ... -->
    </NuxtClientFallback>
  </template>
  ```

## 属性

- `placeholderTag` | `fallbackTag`：指定在服务端渲染失败时用作替代的标签。
  - **类型**：`string`
  - **默认值**：`div`
- `placeholder` | `fallback`：指定服务端渲染失败时显示的替代内容。
  - **类型**：`string`
- `keepFallback`：如果服务端渲染失败，是否保留替代内容。
  - **类型**：`boolean`
  - **默认值**：`false`

::warning{icon="i-ph-warning-duotone"}
`placeholder` 和 `fallback` 属性会将内容作为原始 HTML 渲染。请勿向这些属性传入不可信的用户输入，以免导致 XSS 漏洞。如需动态内容且需要适当转义，请使用 `#fallback` 或 `#placeholder` 插槽。
::

```vue
<template>
  <!-- 如果默认插槽在服务端渲染失败，则使用 <span>Hello world</span> 渲染 -->
  <NuxtClientFallback
    fallback-tag="span"
    fallback="Hello world"
  >
    <BrokeInSSR />
  </NuxtClientFallback>
</template>
```

## 插槽

- `#fallback`：指定当默认插槽在服务端渲染失败时显示的内容。

```vue
<template>
  <NuxtClientFallback>
    <!-- ... -->
    <template #fallback>
      <!-- 如果默认插槽在 SSR 中渲染失败，该内容会在服务端渲染 -->
      <p>Hello world</p>
    </template>
  </NuxtClientFallback>
</template>
```

---

- [源码（客户端）](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-fallback.client.ts)
- [源码（服务端）](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/client-fallback.server.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.