如何实现增量静态再生 (ISR)

示例

增量静态再生 (ISR) 使您能够：

无需重建整个站点即可更新静态内容
通过为大多数请求提供预渲染的静态页面来减少服务器负载
确保自动为页面添加正确的 cache-control 头
处理大量内容页面而无需长时间的 next build 构建

以下是一个最小示例：

interface Post {
  id: string
  title: string
  content: string
}

// 当请求到达时，Next.js 最多每 60 秒使缓存失效一次。
export const revalidate = 60

// 我们仅在构建时预渲染来自 `generateStaticParams` 的参数。
// 如果请求的路径尚未生成，
// Next.js 将按需服务端渲染该页面。
export const dynamicParams = true // 或 false，对未知路径返回 404

export async function generateStaticParams() {
  const posts: Post[] = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )
  return posts.map((post) => ({
    id: String(post.id),
  }))
}

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const post: Post = await fetch(`https://api.vercel.app/blog/${id}`).then(
    (res) => res.json()
  )
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  )
}

这个示例的工作原理：

在 next build 期间，所有已知的博客文章都会被生成（本例中有 25 篇）
对这些页面的所有请求（例如 /blog/1）都会被缓存并且是即时的
60 秒过后，下一个请求仍会显示缓存的（过时的）页面
缓存失效，新版本的页面开始在后台生成
一旦成功生成，Next.js 将显示并缓存更新后的页面
如果请求 /blog/26，Next.js 将按需生成并缓存此页面

参考

路由段配置

函数

示例

基于时间的重新验证

这个示例在 /blog 上获取并显示博客文章列表。一小时后，该页面的缓存将在下一次访问时失效。然后，在后台，使用最新的博客文章生成新版本的页面。

interface Post {
  id: string
  title: string
  content: string
}

export const revalidate = 3600 // 每小时失效一次

export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts: Post[] = await data.json()
  return (
    <main>
      <h1>博客文章</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </main>
  )
}

我们建议设置较高的重新验证时间。例如，1 小时而不是 1 秒。如果需要更精确的控制，请考虑使用按需重新验证。如果需要实时数据，请考虑切换到动态渲染。

使用 `revalidatePath` 进行按需重新验证

对于更精确的重新验证方法，可以使用 revalidatePath 函数按需使页面失效。

例如，这个服务器操作将在添加新文章后被调用。无论您在服务器组件中使用 fetch 还是连接到数据库来获取数据，这都将清除整个路由的缓存，并允许服务器组件获取新数据。

'use server'

import { revalidatePath } from 'next/cache'

export async function createPost() {
  // 使缓存中的 /posts 路由失效
  revalidatePath('/posts')
}

查看演示和探索源代码。

使用 `revalidateTag` 进行按需重新验证

对于大多数用例，建议使整个路径失效。如果需要更细粒度的控制，可以使用 revalidateTag 函数。例如，您可以标记单个 fetch 调用：

export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog', {
    next: { tags: ['posts'] },
  })
  const posts = await data.json()
  // ...
}

如果使用 ORM 或连接到数据库，可以使用 unstable_cache：

import { unstable_cache } from 'next/cache'
import { db, posts } from '@/lib/db'

const getCachedPosts = unstable_cache(
  async () => {
    return await db.select().from(posts)
  },
  ['posts'],
  { revalidate: 3600, tags: ['posts'] }
)

export default async function Page() {
  const posts = getCachedPosts()
  // ...
}

然后可以在服务器操作或路由处理程序中使用 revalidateTag：

'use server'

import { revalidateTag } from 'next/cache'

export async function createPost() {
  // 使缓存中所有标记为 'posts' 的数据失效
  revalidateTag('posts')
}

处理未捕获的异常

如果在尝试重新验证数据时抛出错误，将继续从缓存中提供上次成功生成的数据。在后续的下一个请求中，Next.js 将重试重新验证数据。了解更多关于错误处理的信息。

自定义缓存位置

如果您希望将缓存的页面和数据持久化到持久存储中，或者在 Next.js 应用程序的多个容器或实例之间共享缓存，可以配置 Next.js 缓存位置。了解更多。

故障排除

在本地开发中调试缓存数据

如果使用 fetch API，可以添加额外的日志记录来了解哪些请求被缓存或未被缓存。了解更多关于 logging 选项的信息。

next.config.js

module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
}

验证生产环境行为

要验证您的页面在生产环境中是否正确缓存和重新验证，可以在本地运行 next build 然后运行 next start 来启动生产环境的 Next.js 服务器进行测试。

这将允许您测试增量静态再生 (ISR) 在生产环境中的工作方式。如需进一步调试，请在 .env 文件中添加以下环境变量：

.env

NEXT_PRIVATE_DEBUG_CACHE=1

这将使 Next.js 服务器在控制台输出 ISR 缓存的命中与未命中情况。您可以检查输出结果，查看哪些页面是在 next build 过程中生成的，以及访问路径时页面是如何按需更新的。

注意事项

ISR 仅在使用 Node.js 运行时（默认）时支持。
创建静态导出 (Static Export) 时不支持 ISR。
如果在静态渲染的路由中有多个 fetch 请求，且每个请求有不同的 revalidate 频率，ISR 将使用最短的时间。但这些重新验证频率仍会被数据缓存 (Data Cache) 遵循。
如果路由中使用的任何 fetch 请求的 revalidate 时间为 0，或显式设置为 no-store，则该路由将进行动态渲染 (dynamic rendering)。
按需 ISR 请求不会执行中间件 (Middleware)，这意味着任何路径重写或中间件中的逻辑都不会应用。请确保您重新验证的是确切的路径。例如，使用 /post/1 而不是重写后的 /post-1。

平台支持

部署选项	支持情况
Node.js 服务器	是
Docker 容器	是
静态导出	否
适配器	平台相关

了解如何配置 ISR 当自托管 Next.js 时。

版本历史

版本	变更
`v14.1.0`	自定义 `cacheHandler` 稳定可用。
`v13.0.0`	引入应用路由 (App Router)。
`v12.2.0`	页面路由 (Pages Router)：按需 ISR 稳定可用
`v12.0.0`	页面路由 (Pages Router)：新增 Bot-aware ISR 回退功能。
`v9.5.0`	页面路由 (Pages Router)：引入稳定的 ISR。

On this page