---
title: "<NuxtIsland>"
description: "Nuxt 提供了 <NuxtIsland> 组件，用于渲染无任何客户端 JS 的非交互组件。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/components/nuxt-island"
---
# \<NuxtIsland>

> Nuxt 提供了 \<NuxtIsland> 组件，用于渲染无任何客户端 JS 的非交互组件。

当渲染一个岛屿组件时，该岛屿组件的内容是静态的，因此不会在客户端下载任何 JS。

更改岛屿组件的 props 会触发重新获取岛屿组件以重新渲染。

::note
应用的全局样式会随响应一起发送。
::

::tip
仅服务器组件在底层使用 `<NuxtIsland>`。
::

## Props

- `name` ：要渲染的组件名称。
  - **类型**：`string`
  - **必需**
- `lazy`：使组件非阻塞加载。
  - **类型**：`boolean`
  - **默认值**：`false`
- `props`：传递给渲染组件的属性。
  - **类型**：`Record<string, any>`
- `source`：调用远程资源以渲染该岛屿。
  - **类型**：`string`
- **dangerouslyLoadClientComponents**：加载远程源组件时必需。
  - **类型**：`boolean`
  - **默认值**：`false`

::note
远程岛屿需要在你的 `nuxt.config` 中将 `experimental.componentIslands` 设置为 `'local+remote'`。
::

::warning{icon="i-ph-warning-duotone"}
使用 `source` 属性从远程服务器渲染内容本质上是危险的。当你指定远程 `source` 时，你完全信任该服务器提供安全的 HTML 内容，这些内容将直接渲染在你的应用中。

这类似于使用带有外部内容的 `v-html` ——远程服务器可以注入任何 HTML，包括可能的恶意内容。**仅对你完全信任和控制的服务器使用 `source`。**

`dangerouslyLoadClientComponents` 属性控制着额外的风险层面：是否也从远程源下载并执行客户端组件。即使禁用 `dangerouslyLoadClientComponents`（默认情况），你仍在信任远程服务器的 HTML 输出。
::

::note
Component props and context are sent as GET query parameters to enable caching. Query parameters may be visible in server access logs, CDN caches, and HTTP `Referer` headers.
::

::note
默认情况下，会从 `~/components/islands/` 目录扫描组件岛屿。因此 `~/components/islands/MyIsland.vue` 组件可以通过 `<NuxtIsland name="MyIsland" />` 来渲染。
::

## Slots

如果声明了插槽，可以向岛屿组件传递插槽。

每个插槽都是交互式的，因为提供插槽的是父组件。

某些插槽为 `NuxtIsland` 保留，用于特殊情况。

- `#fallback`：指定岛屿加载前（如果组件为懒加载）或 `NuxtIsland` 获取组件失败时显示的内容。

## Ref

- `refresh()`
  - **类型**：`() => Promise<void>`
  - **描述**：通过重新获取服务端组件来强制刷新组件。

## Events

- `error`
  - **parameters**:
    - **error**:
      - **type**: `unknown`
  - **description**：当 `NuxtIsland` 获取新的岛屿失败时触发。

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-island.ts)


## Sitemap

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