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:
- State 与事件处理器。例如
onClick、onChange。 - 生命周期逻辑。例如
useEffect。 - 仅限浏览器的 API。例如
localStorage、window、navigator.geolocation等。 - 自定义 Hook。
在需要以下功能时使用 Server Components:
- 从数据库或 API 获取数据,靠近数据源。
- 使用 API 密钥、令牌和其他机密信息,而无需将它们暴露给客户端。
- 减少发送到浏览器的 JavaScript 数量。
- 改善 First Contentful Paint (FCP)(首次内容绘制),并逐步将内容流式传输到客户端。
例如,<Page> 组件是一个 Server Component,它获取关于某篇文章的数据,并将其作为 props 传递给处理客户端交互的 <LikeButton>。
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>
)
}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>
)
}'use client'
import { useState } from 'react'
export default function LikeButton({ likes }: { likes: number }) {
// ...
}'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
在客户端(首次加载)#
然后,在客户端:
- HTML 用于立即向用户展示路由的快速、非交互式预览。
- RSC Payload 用于协调 Client 与 Server 组件树。
- JavaScript 用于对 Client Components 进行 hydrate(水合),使应用具有交互性。
什么是 hydrate(水合)?
hydrate(水合)是 React 将事件处理器附加到 DOM,使静态 HTML 具有交互性的过程。
后续导航#
在后续导航中:
- RSC Payload 被预取并缓存,以实现即时导航。
- Client Components 完全在客户端渲染,不使用服务端渲染的 HTML。
示例#
使用 Client Components#
你可以通过在文件顶部、导入语句之前添加 "use client" 指令来创建 Client Component。
'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'
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。
// 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>
</>
)
}// 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>
</>
)
}'use client'
export default function Search() {
// ...
}'use client'
export default function Search() {
// ...
}从 Server 组件向 Client 组件传递数据#
你可以使用 props 将数据从 Server Components 传递到 Client Components。
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} />
}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} />
}'use client'
export default function LikeButton({ likes }: { likes: number }) {
// ...
}'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> 组件内部。
'use client'
export default function Modal({ children }: { children: React.ReactNode }) {
return <div>{children}</div>
}'use client'
export default function Modal({ children }) {
return <div>{children}</div>
}然后,在父级 Server Component(例如 <Page>)中,你可以将 <Cart> 作为 <Modal> 的子组件传递:
import Modal from './ui/modal'
import Cart from './ui/cart'
export default function Page() {
return (
<Modal>
<Cart />
</Modal>
)
}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:
'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>
}'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)中:
import ThemeProvider from './theme-provider'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<body>
<ThemeProvider>{children}</ThemeProvider>
</body>
</html>
)
}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 />,它将按预期工作:
'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>
)
}'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 中:
'use client'
import { Carousel } from 'acme-carousel'
export default Carousel'use client'
import { Carousel } from 'acme-carousel'
export default Carousel现在,你可以直接在 Server Component 中使用 <Carousel />:
import Carousel from './carousel'
export default function Page() {
return (
<div>
<p>View pictures</p>
<Carousel />
</div>
)
}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 模块之间共享。这意味着有可能意外地将仅限服务端的代码导入到客户端。例如,考虑以下函数:
export async function getData() {
const res = await fetch('https://external-service.com/data', {
headers: {
authorization: process.env.API_KEY,
},
})
return res.json()
}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 包。
然后,将该包导入到包含仅限服务端代码的文件中:
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 规则会标记多余的依赖,你可以安装它们以避免问题。
npm install server-onlyyarn add server-onlypnpm add server-onlybun add server-onlyNext.js 在内部处理 server-only 和 client-only 的导入,以便在模块被用于错误的环境时提供更清晰的错误消息。Next.js 不会使用来自 NPM 的这些包的内容。
Next.js 还为 server-only 和 client-only 提供了自己的类型声明,适用于启用了 noUncheckedSideEffectImports 的 TypeScript 配置。