NNext.js 中文网 GitHub

fetch

扩展的 fetch 函数的 API 参考。

Next.js 扩展了 Web fetch() API,允许服务端的每个请求设置自己的持久缓存和重新验证语义。

在浏览器中,cache 选项指示 fetch 请求将如何与浏览器的 HTTP 缓存交互。通过此扩展,cache 指示服务端 fetch 请求将如何与框架的持久缓存交互。

你可以在 Server Components 中直接使用 async 和 await 调用 fetch。

app/page.tsx
export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}
app/page.js
export default async function Page() {
  let data = await fetch('https://api.vercel.app/blog')
  let posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

fetch(url, options)#

由于 Next.js 扩展了 Web fetch() API,你可以使用任何可用的原生选项。

options.cache#

配置请求应如何与 Next.js 缓存交互。

ts
fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
  • auto no cache(默认):在开发环境中,Next.js 会在每次请求时从远程服务器获取资源,但在 next build 期间只会获取一次,因为路由会被静态预渲染。如果在路由上检测到 Request-time API,Next.js 会在每次请求时获取资源。
  • no-store:Next.js 会在每次请求时从远程服务器获取资源,即使路由上没有检测到 Request-time API。
  • force-cache:Next.js 在其服务端缓存中查找匹配的请求。请求根据其 URL、方法、请求头和主体进行匹配,因此其中任何一项不同的请求都会被分别缓存。
    • 如果存在匹配项且它是新鲜的,则从缓存中返回。
    • 如果没有匹配项或匹配项已过期,Next.js 会从远程服务器获取资源,并用下载的资源更新缓存。只有 HTTP 状态码为 200 的响应会被存储。

小知识: 缓存是选择启用的。设置 cache: 'force-cache' 可缓存任何请求,包括 POST 以及发送 authorization 或 cookie 请求头的请求。Draft Mode 会完全绕过缓存(不进行读取或写入)。

options.next.revalidate#

ts
fetch(`https://...`, { next: { revalidate: false | 0 | number } })

设置资源的缓存生命周期(以秒为单位)。

  • false - 无限期缓存资源。语义上等同于 revalidate: Infinity。HTTP 缓存可能会随着时间推移淘汰较旧的资源。
  • 0 - 阻止资源被缓存。
  • number - (以秒为单位)指定资源的缓存生命周期最多为 n 秒。

小知识:

  • 如果单个 fetch() 请求设置的 revalidate 数值低于某个路由的默认 revalidate,则整个路由的重新验证间隔都会被缩短。
  • 如果同一路由中两个 URL 相同的 fetch 请求设置了不同的 revalidate 值,将使用较小的值。
  • 不允许使用相互冲突的选项,例如 { revalidate: 3600, cache: 'no-store' },两者都会被忽略,并且在开发模式下会向终端打印警告。

options.next.tags#

ts
fetch(`https://...`, { next: { tags: ['collection'] } })

设置资源的缓存标签。然后可以使用 revalidateTag 按需重新验证数据。自定义标签的最大长度为 256 个字符,标签项的最大数量为 128 个。

记忆化(Memoization)#

在一次服务端渲染过程中,使用 GET 且 URL 和选项相同的 fetch 请求会自动被记忆化。如果你在多个 Server Components、布局、页面、generateStaticParams 和 generateViewport 中调用相同的 fetch,Next.js 只会执行一次并共享结果。这与持久缓存不同:记忆化只持续一次渲染过程,而缓存的响应会跨请求持久存在。

要退出记忆化,请向 fetch 传入 AbortController 的 signal:

js
const { signal } = new AbortController()
fetch(url, { signal })

小知识: 记忆化不适用于 Route Handlers,因为它们不是 React 组件树的一部分。

故障排除#

默认情况下 fetch 的 auto no cache 和 cache: 'no-store' 在开发环境中未显示最新数据#

在本地开发中,Next.js 会在热模块替换(HMR)之间缓存 Server Components 中的 fetch 响应,以加快响应速度并降低计费 API 调用的成本。

默认情况下,HMR 缓存适用于所有 fetch 请求,包括使用默认 auto no cache 和 cache: 'no-store' 选项的请求。这意味着未缓存的请求在 HMR 刷新之间不会显示最新数据。不过,在导航或整页重新加载时,缓存会被清除。

有关更多信息,请参阅 serverComponentsHmrCache 文档。

开发中的硬刷新与缓存#

在开发模式下,如果请求包含 cache-control: no-cache 请求头,options.cache、options.next.revalidate 和 options.next.tags 都将被忽略,fetch 请求将直接从源获取。

当在开发者工具中禁用缓存或进行硬刷新时,浏览器通常会包含 cache-control: no-cache。

版本历史#

版本变更
v13.0.0引入 fetch。
Next.js 中文网