io
io 函数的 API 参考。
启用 Cache Components 后,Next.js 需要你决定是捕获一次 new Date() 或 Math.random() 这样的同步值并为每位访问者复用它,还是为每个请求重新生成它。
要在静态外壳中捕获该值,请用 "use cache"包裹它。要使其不进入静态外壳,请使用 await io(),它会在预渲染期间挂起。
在请求期间、缓存作用域内、浏览器中以及未启用 Cache Components 的应用(包括 Pages Router)中,调用 io() 会立即解析。
用法#
调用 io() 以告知 Next.js 接下来是一个 IO 操作。
在 Server Component 中,在读取 new Date()、Math.random()、crypto.randomUUID() 之类的值或同步数据库驱动(如 node:sqlite)之前,先调用 await io():
import { Suspense } from 'react'
import { io } from 'next/cache'
export default function Page() {
return (
<Suspense fallback={<p>Loading...</p>}>
<CurrentTime />
</Suspense>
)
}
async function CurrentTime() {
await io()
return <p>{new Date().toISOString()}</p>
}import { Suspense } from 'react'
import { io } from 'next/cache'
export default function Page() {
return (
<Suspense fallback={<p>Loading...</p>}>
<CurrentTime />
</Suspense>
)
}
async function CurrentTime() {
await io()
return <p>{new Date().toISOString()}</p>
}在此路由中,CurrentTime 被包裹在 <Suspense> 边界中;预渲染期间,await io() 会挂起,fallback 会随静态外壳一起发送。如果 CurrentTime 改为在 "use cache" 作用域内渲染,io() 将是空操作,该值会被捕获到静态外壳中,且无需 <Suspense> 边界。
在 Client Component 中,在读取 Date.now() 之类的同步来源之前,使用 React 的 use Hook 调用 io()。Client Component 在 SSR 期间会在服务端预渲染,否则该读取会被包含在静态外壳中:
'use client'
import { use } from 'react'
import { io } from 'next/cache'
export function CurrentTime() {
use(io())
return <div>{Date.now()}</div>
}'use client'
import { use } from 'react'
import { io } from 'next/cache'
export function CurrentTime() {
use(io())
return <div>{Date.now()}</div>
}何时不需要 io()#
如果某个操作已经会挂起预渲染,例如 <Suspense> 内未缓存的 fetch 或异步数据库查询,则无需在其前面额外调用 io()。
请求数据之后的同步 IO#
在构建时预渲染期间,await cookies() 或 headers() 会在以下代码执行前挂起。借助 Partial Prefetching,这些 API 可以在运行时预渲染期间解析。在这些 API 之后未缓存地读取时间或随机值仍可能触发预渲染错误,即使位于 <Suspense> 内。
在同步读取之前,或在调用执行该读取的辅助函数之前,调用 await io()。要让该辅助函数仍可用于运行时预取,请在 use cache 作用域之外读取所需的请求值并将其作为参数传入,并将同步读取包含在缓存作用域内。
io() 与 connection() 的区别#
与 connection() 不同,io() 也可在 "use cache" 作用域内使用,在那里它会立即解析,因此调用它的函数可以在缓存和非缓存代码中都能运行。在缓存作用域内调用 connection() 会抛出错误。在缓存作用域之外,两者行为相同:无论预渲染是在构建时还是为预取而运行,两者之后的代码都会被排除在所有预渲染之外。优先使用 io() 而非 connection(),仅在需要等待真实用户请求时才使用 connection()。
参考#
类型#
function io(): Promise<void>参数#
- 该函数不接受任何参数。
返回值#
一个 Promise<void>。启用 Cache Components 后,await 该 promise 会停止预渲染,从而将后续代码排除在预渲染输出之外。在其他所有上下文(真实请求、缓存作用域、generateStaticParams、浏览器以及未启用 Cache Components 的路由)中,它会立即解析。
版本历史#
| 版本 | 变更 |
|---|---|
v16.3.0 | 新增 io。 |