跳到主要内容

fetch

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

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

你可以直接在服务端组件中使用 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>
  )
}

fetch(url, options)​

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

options.cache​

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

fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
  • auto no cache（默认）：Next.js 在开发环境中对每个请求从远程服务器获取资源，但会在 next build 期间获取一次，因为路由将被静态预渲染。如果在路由上检测到 动态 API，Next.js 将对每个请求获取资源。
  • no-store：Next.js 对每个请求从远程服务器获取资源，即使在路由上未检测到动态 API。
  • force-cache：Next.js 在其数据缓存中查找匹配的请求。
    • 如果有匹配且是新鲜的，将从缓存返回。
    • 如果没有匹配或匹配已过时，Next.js 将从远程服务器获取资源并使用下载的资源更新缓存。

options.next.revalidate​

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​

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

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

故障排除​

Fetch 默认 auto no store 和 cache: 'no-store' 在开发中不显示新鲜数据​

Next.js 在本地开发中跨热模块替换（HMR）缓存服务端组件中的 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。
最后于 更新