NNext.js 中文网 GitHub

Server 与 Client 组件

了解如何使用 React Server 与 Client 组件在服务端或客户端渲染应用的部分内容。

默认情况下,layout 和 page 是 Server Components,这使你可以在服务端获取数据、渲染 UI 的部分内容,可选择缓存结果,并将其流式传输到客户端。当你需要交互性或浏览器 API 时,可以使用 Client Components 来叠加功能。

本页解释 Server 与 Client 组件在 Next.js 中如何工作、何时使用它们,并通过示例展示如何在应用中将它们组合在一起。

小知识: 关于每种组件类型在哪里运行以及边界如何工作的说明,请参阅 Server 与 Client 边界。

何时使用 Server 与 Client 组件?#

客户端和服务端环境具有不同的能力。Server 与 Client 组件使你能够根据用例在各自环境中运行逻辑。

在需要以下功能时使用 Client Components:

在需要以下功能时使用 Server Components:

  • 从数据库或 API 获取数据,靠近数据源。
  • 使用 API 密钥、令牌和其他机密信息,而无需将它们暴露给客户端。
  • 减少发送到浏览器的 JavaScript 数量。
  • 改善 First Contentful Paint (FCP)(首次内容绘制),并逐步将内容流式传输到客户端。

例如,<Page> 组件是一个 Server Component,它获取关于某篇文章的数据,并将其作为 props 传递给处理客户端交互的 <LikeButton>。

app/[id]/page.tsx
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post = await getPost(id)

  return (
    <div>
      <main>
        <h1>{post.title}</h1>
        
        <LikeButton likes={post.likes} />
      </main>
    </div>
  )
}
app/[id]/page.js
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({ params }) {
  const { id } = await params
  const post = await getPost(id)

  return (
    <div>
      <main>
        <h1>{post.title}</h1>
        
        <LikeButton likes={post.likes} />
      </main>
    </div>
  )
}
app/ui/like-button.tsx
'use client'

import { useState } from 'react'

export default function LikeButton({ likes }: { likes: number }) {
  // ...
}
app/ui/like-button.js
'use client'

import { useState } from 'react'

export default function LikeButton({ likes }) {
  // ...
}

Server 与 Client 组件在 Next.js 中如何工作?#

在服务端#

在服务端,Next.js 使用 React 的 API 来编排渲染。渲染工作按各个路由段(layout 与 page)拆分成块,包括并行路由插槽,无论它们是否显示:

  • Server Components 被渲染成一种称为 React Server Component Payload(RSC Payload)的特殊数据格式。
  • Client Components 与 RSC Payload 被用于预渲染 HTML。

什么是 React Server Component Payload(RSC)?

RSC Payload 是渲染后的 React Server Components 树的紧凑序列化表示。React 在客户端使用它来更新浏览器的 DOM。RSC Payload 包含:

  • Server Components 的渲染结果
  • Client Components 应渲染位置的占位符,以及对其 JavaScript 文件的引用
  • 从 Server Component 传递给 Client Component 的所有 props

在客户端(首次加载)#

然后,在客户端:

  1. HTML 用于立即向用户展示路由的快速、非交互式预览。
  2. RSC Payload 用于协调 Client 与 Server 组件树。
  3. JavaScript 用于对 Client Components 进行 hydrate(水合),使应用具有交互性。

什么是 hydrate(水合)?

hydrate(水合)是 React 将事件处理器附加到 DOM,使静态 HTML 具有交互性的过程。

后续导航#

在后续导航中:

  • RSC Payload 被预取并缓存,以实现即时导航。
  • Client Components 完全在客户端渲染,不使用服务端渲染的 HTML。

示例#

使用 Client Components#

你可以通过在文件顶部、导入语句之前添加 "use client" 指令来创建 Client Component。

app/ui/counter.tsx
'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>{count} likes</p>
      <button onClick={() => setCount(count + 1)}>Click me</button>
    </div>
  )
}
app/ui/counter.js
'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>{count} likes</p>
      <button onClick={() => setCount(count + 1)}>Click me</button>
    </div>
  )
}

"use client" 用于声明 Server 与 Client 模块图(树)之间的边界。

一旦某个文件被标记为 "use client",它的所有导入以及它直接渲染的组件都会被包含在客户端 bundle 中。这意味着你不需要为每一个面向客户端的组件都添加该指令。

此行为适用于属于 Client Component 模块图一部分的组件,包括它导入的模块和它直接渲染的组件。它不适用于作为 children 或其他 props 传递的 Server Components。这些组件不会被导入到 Client Component 的模块图中。它们在服务端渲染,并作为渲染结果传递给 Client Component。

关于如何组合 Server 与 Client 组件,请参阅 交错使用 Server 与 Client 组件。

减小 JS bundle 体积#

为了减小客户端 JavaScript bundle 的体积,请在定义交互组件的文件顶部添加 'use client',而不是将 UI 的大部分标记为 Client Components。

例如,<Layout> 组件主要包含 logo 和导航链接等静态元素,但包含一个交互式搜索栏。<Search /> 需要成为 Client Component,而 layout 的其余部分可以保持为 Server Component。

app/layout.tsx
// Client Component
import Search from './search'
// Server Component
import Logo from './logo'

// Layout 默认是 Server Component
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Logo />
        <Search />
      </nav>
      <main>{children}</main>
    </>
  )
}
app/layout.js
// Client Component
import Search from './search'
// Server Component
import Logo from './logo'

// Layout 默认是 Server Component
export default function Layout({ children }) {
  return (
    <>
      <nav>
        <Logo />
        <Search />
      </nav>
      <main>{children}</main>
    </>
  )
}
app/ui/search.tsx
'use client'

export default function Search() {
  // ...
}
app/ui/search.js
'use client'

export default function Search() {
  // ...
}

从 Server 组件向 Client 组件传递数据#

你可以使用 props 将数据从 Server Components 传递到 Client Components。

app/[id]/page.tsx
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post = await getPost(id)

  return <LikeButton likes={post.likes} />
}
app/[id]/page.js
import LikeButton from '@/app/ui/like-button'
import { getPost } from '@/lib/data'

export default async function Page({ params }) {
  const { id } = await params
  const post = await getPost(id)

  return <LikeButton likes={post.likes} />
}
app/ui/like-button.tsx
'use client'

export default function LikeButton({ likes }: { likes: number }) {
  // ...
}
app/ui/like-button.js
'use client'

export default function LikeButton({ likes }) {
  // ...
}

或者,你可以使用 use API 将数据从 Server Component 流式传输到 Client Component。请参阅示例。

小知识:传递给 Client Components 的 props 需要能被 React 序列化。

交错使用 Server 与 Client 组件#

你可以将 Server Components 作为 prop 传递给 Client Component。这使你可以在 Client 组件中直观地嵌套服务端渲染的 UI。

一种常见模式是使用 children 在 <ClientComponent> 中创建一个插槽。例如,一个在服务端获取数据的 <Cart> 组件,位于使用客户端状态来切换可见性的 <Modal> 组件内部。

app/ui/modal.tsx
'use client'

export default function Modal({ children }: { children: React.ReactNode }) {
  return <div>{children}</div>
}
app/ui/modal.js
'use client'

export default function Modal({ children }) {
  return <div>{children}</div>
}

然后,在父级 Server Component(例如 <Page>)中,你可以将 <Cart> 作为 <Modal> 的子组件传递:

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

export default function Page() {
  return (
    <Modal>
      <Cart />
    </Modal>
  )
}
app/page.js
import Modal from './ui/modal'
import Cart from './ui/cart'

export default function Page() {
  return (
    <Modal>
      <Cart />
    </Modal>
  )
}

在这种模式下,Server Components 会在服务端提前渲染,即使作为 props 传递给 Client Components 也是如此。React Server Component Payload 包含这些 Server Components 的渲染结果,以及 Client Components 应渲染位置的占位符和对其 JavaScript 文件的引用。

Context Provider#

React context 通常用于共享全局状态,例如当前主题。但是,Server Components 不支持 React context。

要使用 context,请创建一个接受 children 的 Client Component:

app/theme-provider.tsx
'use client'

import { createContext } from 'react'

export const ThemeContext = createContext({})

export default function ThemeProvider({
  children,
}: {
  children: React.ReactNode
}) {
  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
}
app/theme-provider.js
'use client'

import { createContext } from 'react'

export const ThemeContext = createContext({})

export default function ThemeProvider({ children }) {
  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
}

然后,将其导入到一个 Server Component(例如 layout)中:

app/layout.tsx
import ThemeProvider from './theme-provider'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}
app/layout.js
import ThemeProvider from './theme-provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

现在,你的 Server Component 将能够直接渲染你的 provider,应用中所有其他 Client Components 也将能够使用这个 context。

小知识:你应该在树中尽可能深的位置渲染 provider——注意 ThemeProvider 只包裹 {children},而不是整个 <html> 文档。这使 Next.js 更容易优化 Server Components 的静态部分。

要通过 context 传递服务端获取的数据并在 Client Components 中使用 use() 读取它,请参阅在 Context Provider 中使用 React 的 use。

第三方组件#

当使用依赖仅限客户端功能的第三方组件时,你可以将其包装在 Client Component 中,以确保其按预期工作。

例如,可以从 acme-carousel 包导入 <Carousel />。该组件使用了 useState,但定义它的模块还没有 "use client" 指令。

如果你在 Client Component 中使用 <Carousel />,它将按预期工作:

app/gallery.tsx
'use client'

import { useState } from 'react'
import { Carousel } from 'acme-carousel'

export default function Gallery() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>View pictures</button>
      
      {isOpen && <Carousel />}
    </div>
  )
}
app/gallery.js
'use client'

import { useState } from 'react'
import { Carousel } from 'acme-carousel'

export default function Gallery() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>View pictures</button>
      
      {isOpen && <Carousel />}
    </div>
  )
}

但是,如果你尝试直接在 Server Component 中使用它,你会看到一个错误。这是因为 Next.js 不知道 <Carousel /> 使用了仅限客户端的功能。

要解决这个问题,你可以将依赖仅限客户端功能的第三方组件包装在你自己的 Client Components 中:

app/carousel.tsx
'use client'

import { Carousel } from 'acme-carousel'

export default Carousel
app/carousel.js
'use client'

import { Carousel } from 'acme-carousel'

export default Carousel

现在,你可以直接在 Server Component 中使用 <Carousel />:

app/page.tsx
import Carousel from './carousel'

export default function Page() {
  return (
    <div>
      <p>View pictures</p>
      
      <Carousel />
    </div>
  )
}
app/page.js
import Carousel from './carousel'

export default function Page() {
  return (
    <div>
      <p>View pictures</p>
      
      <Carousel />
    </div>
  )
}

给库作者的建议

如果你正在构建组件库,请为依赖仅限客户端功能的入口点添加 "use client" 指令。这样你的用户就可以将组件导入 Server Components,而无需创建包装器。

值得注意的是,一些打包工具可能会移除 "use client" 指令。你可以在 React Wrap Balancer 和 Vercel Analytics 仓库中找到如何配置 esbuild 以包含 "use client" 指令的示例。

防止环境污染#

JavaScript 模块可以在 Server 和 Client Components 模块之间共享。这意味着有可能意外地将仅限服务端的代码导入到客户端。例如,考虑以下函数:

lib/data.ts
export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })

  return res.json()
}
lib/data.js
export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })

  return res.json()
}

此函数包含一个绝不应暴露给客户端的 API_KEY。

在 Next.js 中,只有以 NEXT_PUBLIC_ 为前缀的环境变量才会被包含在客户端 bundle 中。如果变量没有该前缀,Next.js 会将它们替换为空字符串。

因此,即使 getData() 可以被导入并在客户端执行,它也不会按预期工作。

为防止在 Client Components 中意外使用,你可以使用 server-only 包。

然后,将该包导入到包含仅限服务端代码的文件中:

lib/data.js
import 'server-only'

export async function getData() {
  const res = await fetch('https://external-service.com/data', {
    headers: {
      authorization: process.env.API_KEY,
    },
  })

  return res.json()
}

现在,如果你尝试将该模块导入到 Client Component 中,将会出现构建时错误。

相应的 client-only 包可用于标记包含仅限客户端逻辑的模块,例如访问 window 对象的代码。

在 Next.js 中,安装 server-only 或 client-only 是可选的。但是,如果你的 lint 规则会标记多余的依赖,你可以安装它们以避免问题。

bash · npm
npm install server-only
bash · yarn
yarn add server-only
bash · pnpm
pnpm add server-only
bash · bun
bun add server-only

Next.js 在内部处理 server-only 和 client-only 的导入,以便在模块被用于错误的环境时提供更清晰的错误消息。Next.js 不会使用来自 NPM 的这些包的内容。

Next.js 还为 server-only 和 client-only 提供了自己的类型声明,适用于启用了 noUncheckedSideEffectImports 的 TypeScript 配置。

Next.js 中文网