NNext.js 中文网 GitHub

服务器与客户端边界

了解服务器组件和客户端组件在 App Router 中的运行位置,以及它们之间的边界如何工作。

React Server Components(RSC)将组件树拆分到服务器和客户端模块图中。这条边界决定了组件代码在哪里运行,以及代码是否会被发送到浏览器。RSC 让服务器组件(Server Components)完全保留在服务器上,并保留客户端组件(Client Components)用于交互式 UI。两者组合在一棵树中,服务器将其渲染为 RSC Payload,这是对 UI 的序列化描述,其中包含对内部客户端组件的引用。

在 RSC 之前,React 组件遵循的是 RSC 现在所称的客户端组件模型。React 可以在服务器上将这些组件渲染为 HTML,但相同的代码也会发送到浏览器以水合(hydrate)该 HTML。水合使初始 HTML 具有交互性,并要求组件在服务器和浏览器中产生匹配的输出。完全在客户端渲染的应用则可以从空外壳开始,在浏览器中挂载组件树。

txt
Server Component
├─ Server Component
└─ Client Component
   └─ Client Component

每个组件的模块属于服务器模块图、客户端模块图,或两者兼有。Next.js 会为每种环境分别编译被两个图使用的模块。

在渲染期间,服务器图生成对客户端组件的引用,并序列化传递给它们的 props。客户端图不会导入服务器图。客户端图通过 RSC Payload 接收这些引用和序列化后的 props。

渲染环境#

组件名称暗示服务器和浏览器之间有清晰的划分,但实际上两处都会发生渲染。在服务器上,服务器组件树生成 RSC Payload。Next.js 使用该 payload 和客户端组件在构建时或处理请求时渲染 HTML。

在决定组件在哪里运行时,需要考虑它的服务器渲染以及其代码是否在浏览器中运行:

在服务器上在浏览器中
Server Component是否
Client Component是是

"客户端(Client)"一词表示客户端组件除了在服务器上渲染外,还会在浏览器中运行。

在直接访问时,以下客户端组件会在服务器上渲染,并在水合期间再次在浏览器中渲染。其日志会出现在终端和浏览器控制台中。在客户端导航时,服务器发送 RSC Payload,组件在浏览器中渲染,而没有服务器渲染的 HTML。

app/hello.tsx
'use client'

export default function Hello() {
  console.log('Hello rendered') // 直接访问时:先是服务器,然后是浏览器
  return <p>Hello</p>
}
app/hello.js
'use client'

export default function Hello() {
  console.log('Hello rendered') // 直接访问时:先是服务器,然后是浏览器
  return <p>Hello</p>
}

在服务器上渲染客户端组件会产生 HTML,但该组件仍然是客户端组件。

将客户端组件渲染为 HTML 的做法早于 RSC。根据路由的不同,Next.js 可以生成或重新生成 HTML:

RSC 是一个独立的过程,它将服务器组件代码保留在服务器上,并发出 RSC Payload,而不是发送这些代码。"服务器渲染(Server-rendered)"描述的是 Next.js 如何生成 HTML。"服务器组件(Server Component)"描述的是组件代码在哪里运行以及代码是否发送到浏览器。

服务器组件与 SEO

只读取 HTML 的爬虫只能看到第一个响应,不会运行任何 JavaScript。服务器组件和客户端组件都会为该响应贡献 HTML。

SEO 取决于服务器渲染是否能到达内容。隐藏在用户交互或事件之后的内容不会出现在不运行 JavaScript 的爬虫可获取的 HTML 中。

有关组件何时渲染(是在构建时还是每次请求时、静态还是动态)的详细信息,请参阅渲染理念。

数据如何进入树#

在 RSC 之前,Next.js 应用通常使用 getStaticProps 或 getServerSideProps 等函数收集服务器数据,然后将其作为 props 传递给组件树。数据获取发生在树渲染之前。树接收数据,而不是在渲染期间获取数据。

txt
数据
  ↓
加载器或 API
  ↓
Props
  ↓
组件树

由于服务器组件只在服务器上运行,它可以访问数据库、文件系统、内部服务或机密等资源。组件在自身渲染期间读取这些资源,而无需先通过 API 路由将数据暴露给客户端。

app/page.tsx
import { PostList } from '@/app/ui/post-list'
import { getPosts } from '@/lib/data'

export default async function Page() {
  const posts = await getPosts() // 在服务器上运行,在渲染期间
  return <PostList posts={posts} />
}
app/page.js
import { PostList } from '@/app/ui/post-list'
import { getPosts } from '@/lib/data'

export default async function Page() {
  const posts = await getPosts() // 在服务器上运行,在渲染期间
  return <PostList posts={posts} />
}

借助 RSC,服务器组件可以在渲染时获取数据。无需单独的数据加载步骤来向组件树传递初始 props。

小知识: 由于服务器组件可以直接读取机密和仅限服务器使用的数据,请谨慎考虑传递给客户端组件的内容。

Props 会被序列化并发送到浏览器。请参阅数据安全。

服务器组件无需在返回 UI 前等待所有数据。要将服务器获取的数据流式传输到客户端组件,请在服务器组件中启动请求,并将待处理的 promise 作为 prop 传递。

客户端组件使用 use 将 promise 作为资源读取。当 promise 待处理时,最近的 Suspense 边界会显示其回退内容。当 promise 解析完成时,客户端组件进行渲染。

由于请求在客户端运行之前就已启动,客户端组件无需在挂载后获取相同的数据。当请求的数据依赖仅限客户端的状态或用户交互时,您可能仍需要在浏览器中启动获取。

相同的 fetch 请求会在服务器渲染期间被记忆化。借助缓存组件(Cache Components),您可以缓存数据函数或组件,并独立于页面其余部分重新验证该条目。有关实现模式,请参阅获取数据。

状态与交互性#

服务器组件的代码永远不会到达浏览器。当 Next.js 渲染路由时(例如在导航、刷新或重新验证之后),组件可以再次渲染。

客户端组件的代码确实会到达浏览器。React 在初始加载时水合该组件,客户端更新可以在浏览器中重新渲染它。

小知识: 在初始加载时,RSC Payload 会随 HTML 一起发送。

直接修改服务器组件的 DOM 节点可能导致 DOM 与 React 的组件树不同步。

要更新服务器组件的输出,请在服务器上再次渲染该组件。当浏览器收到新的 RSC Payload 时,React 会协调组件树并更新 DOM。请参阅流式传输。

useState、useEffect 和事件处理程序需要能在浏览器中运行并响应更新的代码。服务器组件代码永远不会到达浏览器,因此无法使用这些客户端 API。

浏览器和 HTML 的内置行为无需客户端组件即可提供交互性。例如:

  • <details> 元素可以展开和收起。
  • <form> 可以通过传递给其 action prop 的 Server Function 提交。
  • <video controls> 元素可以播放和暂停。

当行为需要随时间变化的浏览器状态(例如受控输入、实时筛选或拖拽手柄)时,请使用客户端组件。当浏览器提供了所有必需的行为时,按钮或表单不需要客户端组件。

有关各环境适用内容的实用清单,请参阅何时使用服务器组件和客户端组件。

跨越边界#

通过在文件顶部、任何导入之前添加 'use client' 指令,可以将模块标记为客户端入口点。该指令在模块图中划出一条边界,有两条规则决定什么可以跨越它:

  • 代码通过导入跨越边界。客户端组件导入的任何内容都会被拉入客户端包(client bundle)。
  • 数据通过 props 跨越边界,并且必须是可序列化的,因此事件处理程序等函数无法跨越。

小知识:

从服务器组件向客户端组件传递函数作为 prop 会抛出错误。像 onClick 这样的事件处理程序无法跨越。标记了 'use server' 的 Server Function 会作为引用跨越边界。

从类型上无法将 Server Function 与普通函数区分开来。当客户端组件 prop 的名称为 action 或以 Action 结尾时,TypeScript 插件允许其类型为函数。插件会标记其他函数类型的 props。

渲染后的 React 元素可以跨越边界,因为它是可序列化的数据。将渲染结果作为 children 传递,可以让服务器组件嵌套在客户端组件中,而无需将服务器组件的代码导入客户端图。

app/page.tsx
import { Cart } from '@/app/ui/cart'
import { Modal } from '@/app/ui/modal'

// Page 和 Cart 是服务器组件。Modal 是客户端组件
export default function Page() {
  return (
    <Modal title={<div>Your cart</div>}>
      <Cart />
    </Modal>
  )
}
app/page.js
import { Cart } from '@/app/ui/cart'
import { Modal } from '@/app/ui/modal'

// Page 和 Cart 是服务器组件。Modal 是客户端组件
export default function Page() {
  return (
    <Modal title={<div>Your cart</div>}>
      <Cart />
    </Modal>
  )
}

children prop 的行为与其他 prop 一样。Modal 接收 title 和 children 作为序列化后的 React 元素,然后在其实现定义的位置渲染它们。

app/ui/modal.tsx
'use client'

import { useState, type ReactNode } from 'react'

export function Modal({
  title,
  children,
}: {
  title: ReactNode
  children: ReactNode
}) {
  const [open, setOpen] = useState(true)
  if (!open) return null

  return (
    <div role="dialog">
      <header>
        {title}
        <button onClick={() => setOpen(false)}>Close</button>
      </header>
      {children}
    </div>
  )
}
app/ui/modal.js
'use client'

import { useState } from 'react'

export function Modal({ title, children }) {
  const [open, setOpen] = useState(true)
  if (!open) return null

  return (
    <div role="dialog">
      <header>
        {title}
        <button onClick={() => setOpen(false)}>Close</button>
      </header>
      {children}
    </div>
  )
}

在这里,Cart 在服务器上运行,Modal 只能看到它的输出,永远看不到它的代码。

<details> <summary>所有者与父级</summary>

在此示例中,Page 展示了 React 区分的两种角色:

  • 所有者(owner)是指其源代码中包含子级 JSX 的组件。Page 同时拥有 Modal 和 Cart。
  • 父级(parent)是指在渲染树中直接包含子级的组件。Modal 是 Cart 的父级。

由于 Cart 的所有者是服务器组件,Cart 在服务器上渲染。Modal 只是父级,因此 Modal 接收 Cart 的输出进行放置,但不接收其代码来运行。这种分离使客户端组件能够显示它从未导入过的服务器组件。

</details>

<details> <summary>跨越边界的复合组件</summary>

复合组件可以将子组件作为静态属性公开,例如 Menu.Item 或 Tabs.Panel。当所有部分都是服务器组件或所有部分都是客户端组件时,此模式可在单个图内工作。

当静态成员跨越边界时,此模式就会失效。导入客户端组件的服务器组件收到的是客户端引用,而不是函数。结果是 Menu.Item 为 undefined,React 抛出"Element type is invalid."错误。

从另一个客户端组件中使用复合客户端组件。要从服务器组件中使用其各个部分,请将它们作为命名导出公开,而不是静态属性。

</details>

您只需在客户端子树的入口处添加 'use client',而无需在其内部的每个文件上都添加。从该入口导入的每个模块都会成为客户端模块图的一部分。

要让共享组件保持不变,可以创建一个导入它的客户端组件包装器,并将指令放在该包装器上。包装器使共享模块保持不变,并将边界移近您的应用代码。它还避免给每个调用 useState 或 useEffect 的共享组件都添加该指令。

如果客户端代码在没有边界的情况下进入服务器图,编译器会指出需要该指令的位置。

更多模式请参阅交错使用服务器组件和客户端组件。

有关 Next.js 中使用的其他指令,请参阅指令文档。

Next.js 中文网