NNext.js 中文网 GitHub

指令(Directives)

了解 React 和 Next.js 指令如何定义客户端入口点、Server Function 和缓存输出。

指令是字符串字面量,用于告诉编译器和打包器如何处理其周围的代码。指令本身看起来只是普通字符串,但 Next.js 和 React 会将它们当作指令,用来转换其所覆盖的代码。指令可以创建客户端入口点或 Server Function,也可以缓存函数或组件的输出。

指令定义方作用
'use client'React从 Server Component 创建客户端入口点
'use server'React将服务端函数暴露为 Server Function
'use cache'Next.js根据代码的输入缓存并复用输出

'use cache' 指令还有 'use cache: remote' 和 'use cache: private' 变体。配置自定义缓存处理器以控制缓存条目的存储位置。

小知识: Next.js 在开发和生产环境中都会在编译时应用指令。

错误遮罩层、指示器和堆栈跟踪会指向你的源文件和行号,而不是生成后的输出。

指令的放置位置#

'use client' 指令必须出现在文件顶部,位于任何导入之前。它适用于整个模块,并定义一个文件级边界,因为该模块会被打包并发送到浏览器。你不能在行内使用 'use client'。

将 'use server' 或 'use cache' 放在文件顶部,可将指令应用于每个导出函数。将任一指令放在函数顶部,则仅应用于该函数。

app/data.ts
// 文件级:应用于每个导出
'use cache'

export async function getUser(id: string) {
  return { id }
}
app/data.js
// 文件级:应用于每个导出
'use cache'

export async function getUser(id) {
  return { id }
}
app/user.tsx
// 函数级:仅应用于此函数
export async function User() {
  'use cache'
  return <p>User</p>
}
app/user.js
// 函数级:仅应用于此函数
export async function User() {
  'use cache'
  return <p>User</p>
}

在服务端模块中声明 'use server' 和 'use cache',而不要在 'use client' 模块中声明。

要将 'use server' 或 'use cache' 函数导入到 Client Component 中,请将指令放在服务端模块的顶部。Client Component 会收到一个引用,用于在服务端调用该函数。

当指令只应应用于某个函数或组件时,将其放在该函数内部。当它应应用于多个导出函数时,请将其放在文件顶部,而不是重复书写。

被文件级 'use server' 或 'use cache' 指令覆盖的每个导出函数都必须是 async。

各指令的要求#

指令会对其覆盖的代码施加规则:

  • 'use client' 将其导出标记为服务端与客户端之间的边界。跨越边界的 Client Component props 必须是可序列化的。普通函数(例如事件处理器)无法跨越边界,但 Server Function 可以作为引用跨越边界。
  • 'use server' 将其覆盖的函数标记为 Server Function。Server Function 必须是 async。当从 Client Component 调用时,其参数和返回值会通过网络进行序列化。Client Component 收到的是一个在服务端调用该函数的引用,而不是函数的代码。
  • 'use cache' 根据其输入缓存其覆盖的函数或组件的输出。被缓存的函数和组件必须是 async。它们的参数和返回值必须是可序列化的,但对于缓存代码原样传递而不检查的不可序列化值除外。缓存代码不能直接读取请求时 API,例如 cookies()、headers() 或 searchParams。

当 'use cache' 位于页面或布局文件顶部时,诸如 generateMetadata 和 generateStaticParams 这样的导出函数必须是 async。

放置位置决定缓存内容#

使用 'use cache' 时,放置位置决定缓存条目的作用域。位于页面顶部的指令会缓存页面的输出及其导入的组件。同一指令位于数据函数内部时,只缓存该函数的结果。当某个数据请求承担了开销较大的工作时,应缓存该函数而不是页面。

使用 'use cache: remote' 时,由远程缓存处理器存储条目。较大的条目可能会增加存储和网络成本。

Next.js 中文网