服务器组件

Nuxt 默认会在服务器上渲染你的应用，但随后会将每个组件的 JavaScript 发送到浏览器，并对整个页面进行水合。对于那些在客户端永远不会发生变化的内容密集型组件（Markdown 渲染、语法高亮、CMS 输出），这是一种浪费：用户下载、解析并执行代码，而这些代码唯一的作用只是重新生成页面上已经存在的 HTML。

服务器组件（也称为岛屿组件）则反其道而行之。服务器组件在服务器上渲染，其 HTML 会嵌入页面中，并且不会向客户端发送任何 JavaScript。它的依赖项（Markdown 解析器、高亮库）也会留在服务器上。

启用服务器组件

组件岛由 experimental.componentIslands 控制。默认值为 'auto'，当应用包含服务器组件或岛屿时会自动启用此功能，因此在大多数情况下无需进行任何配置。

如果希望使用远程岛屿或选择性客户端水合，请显式设置该选项：

export default defineNuxtConfig({
  experimental: {
    componentIslands: {
      selectiveClient: true, // 或使用 'deep'，以启用 `nuxt-client`
      remoteIsland: false, // 允许从远程来源渲染岛屿
    },
  },
})

.server.vue 组件

为组件添加 .server 后缀，即可将其设为独立的服务器组件：

-| app/
---| components/
-----| HighlightedMarkdown.server.vue

像使用其他组件一样使用它：

<template>
  <div>
    <!--
      在服务器上渲染；markdown 解析和高亮
      库不会包含在客户端构建包中
     -->
    <HighlightedMarkdown markdown="# Headline" />
  </div>
</template>

~/components/islands/ 中的组件也会注册为 island，并且可以直接使用 <NuxtIsland> 进行渲染，例如使用 <NuxtIsland name="MyIsland" /> 渲染 ~/components/islands/MyIsland.vue。

你还可以将 .server.vue 组件与同名的 .client.vue 组件配对，以实现独立的服务器端和客户端实现。在这种情况下，该组件不是 island：客户端部分会正常进行 hydration。

岛屿如何渲染

服务端组件在底层使用 <NuxtIsland>。渲染岛屿会向专用的岛屿端点发起请求，该请求会：

• 在服务端创建一个全新的、隔离的 Vue 应用，仅用于渲染该组件
• 创建一个“岛屿上下文”，你可以在岛屿内部通过 nuxtApp.ssrContext.islandContext 访问它
• 再次运行你的插件，除非插件设置了 env: { islands: false }（对象语法插件）

由于岛屿与应用的其余部分相互隔离：

• 页面与岛屿之间无法共享状态（provide/inject、Pinia、useState）；请改用 props 传递数据
• 岛屿内部的 useRoute() 反映的是岛屿自身的请求，而不是用户当前所在的页面。如果岛屿需要路由信息，请显式传入，可以通过 props，或通过 <NuxtIsland> 上的 context prop 传入（在岛屿内部通过 nuxtApp.ssrContext.islandContext 读取）
• 渲染岛屿时不会运行路由中间件

Props 会被序列化并作为 GET 查询参数发送。这使岛屿响应可以被缓存，但也意味着：

• props 必须可被 JSON 序列化
• props 受 URL 长度限制，因此应避免传递大量数据
• props 可能会出现在服务器访问日志、CDN 缓存和 Referer 请求头中

<script setup lang="ts">
import type { Component } from 'vue'
import CardA from './CardA.vue'
import CardB from './CardB.vue'

const props = defineProps<{ variant: string }>()
const allowed: Record<string, Component> = { a: CardA, b: CardB }
const component = allowed[props.variant] ?? CardA
</script>

<template>
  <component :is="component" />
</template>

更改岛屿的 props 会触发网络请求，在服务端重新渲染组件，并就地更新其 HTML。

使用 nuxt-client 进行选择性水合

默认情况下，岛屿是静态的，但你可以通过添加 nuxt-client 属性来对其中的单个组件进行水合。这需要启用 experimental.componentIslands.selectiveClient。

<template>
  <div>
    <HighlightedMarkdown markdown="# Headline" />
    <!-- Counter 将在客户端加载并进行水合 -->
    <Counter
      nuxt-client
      :count="5"
    />
  </div>
</template>

标记了 nuxt-client 的组件会作为岛屿的一部分在服务器端渲染，然后由主客户端应用进行水合。只有该组件的代码块会发送到客户端；岛屿的其余部分仍保持静态。

设置 selectiveClient: 'deep' 后，还可以向 nuxt-client 组件传递插槽。这些插槽会在服务器端渲染，并且在客户端不具备交互性。