fetch

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

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

您可以直接在服务端组件 (Server Components) 中使用 async 和 await 调用 fetch。

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 数据缓存 (Data Cache) 交互。

fetch(`https://...`, { cache: 'force-cache' | 'no-store' })

• auto no cache (默认值): 在开发环境中，Next.js 会在每次请求时从远程服务器获取资源，但在执行 next build 时会获取一次，因为路由将被静态预渲染。如果在路由上检测到动态 API (Dynamic APIs)，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 设置为数值，则无需设置 cache 选项。
• 冲突的选项如 { revalidate: 3600, cache: 'no-store' } 将导致错误。

options.next.tags

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

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

故障排除

开发环境中默认 auto no store 和 cache: 'no-store' 不显示最新数据

Next.js 在本地开发中跨热模块替换 (HMR) 缓存服务端组件 (Server Components) 中的 fetch 响应，以实现更快的响应并减少计费 API 调用的成本。

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

更多信息请参阅 serverComponentsHmrCache 文档。

版本历史