指令(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' 放在文件顶部,可将指令应用于每个导出函数。将任一指令放在函数顶部,则仅应用于该函数。
// 文件级:应用于每个导出
'use cache'
export async function getUser(id: string) {
return { id }
}// 文件级:应用于每个导出
'use cache'
export async function getUser(id) {
return { id }
}// 函数级:仅应用于此函数
export async function User() {
'use cache'
return <p>User</p>
}// 函数级:仅应用于此函数
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' 时,由远程缓存处理器存储条目。较大的条目可能会增加存储和网络成本。