NNext.js 中文网 GitHub

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

了解如何使用增量静态再生成在运行时创建或更新静态页面。

<details> <summary>示例</summary>

</details>

小知识:本指南介绍不使用 Cache Components 的 ISR。如果你正在使用 cacheComponents,请改为参阅使用 Cache Components 的 ISR。

增量静态再生成(ISR)使你能够:

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

以下是一个最小示例:

app/blog/[id]/page.tsx
interface Post {
  id: string
  title: string
  content: string
}

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

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>
  )
}
app/blog/[id]/page.jsx
// 当请求到来时,Next.js 会使缓存失效,
// 但最多每 60 秒一次。
export const revalidate = 60

export async function generateStaticParams() {
  const posts = 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 }) {
  const { id } = await params
  const post = await fetch(`https://api.vercel.app/blog/${id}`).then((res) =>
    res.json()
  )
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  )
}

此示例的工作方式如下:

  1. generateStaticParams 通过返回要预渲染的文章列表,为动态路由启用 ISR
  2. 在 next build 期间,会为每篇文章预渲染一个页面
  3. 对这些页面的所有请求(例如 /blog/1)都会被缓存并即时响应
  4. 过了 60 秒后,下一个请求仍会返回缓存的(现已过时的)页面
  5. 缓存失效,页面新版本开始在后台生成
  6. 生成成功后,下一个请求将返回更新后的页面,并将其缓存以供后续请求使用
  7. 如果请求 /blog/26 且该文章存在,则该页面将按需生成。可以通过使用不同的 dynamicParams 值来更改此行为。但是,如果文章不存在,则返回 404。
pages/blog/[id].tsx
import type { GetStaticPaths, GetStaticProps } from 'next'

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

interface Props {
  post: Post
}

export const getStaticPaths: GetStaticPaths = async () => {
  const posts = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )
  const paths = posts.map((post: Post) => ({
    params: { id: String(post.id) },
  }))

  return { paths, fallback: 'blocking' }
}

export const getStaticProps: GetStaticProps<Props> = async ({
  params,
}: {
  params: { id: string }
}) => {
  const post = await fetch(`https://api.vercel.app/blog/${params.id}`).then(
    (res) => res.json()
  )

  return {
    props: { post },
    // 当请求到来时,Next.js 会使缓存失效,
    // 但最多每 60 秒一次。
    revalidate: 60,
  }
}

export default function Page({ post }: Props) {
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  )
}
pages/blog/[id].jsx
export async function getStaticPaths() {
  const posts = await fetch('https://api.vercel.app/blog').then((res) =>
    res.json()
  )
  const paths = posts.map((post) => ({
    params: { id: post.id },
  }))

  return { paths, fallback: 'blocking' }
}

export async function getStaticProps({ params }) {
  const post = await fetch(`https://api.vercel.app/blog/${params.id}`).then(
    (res) => res.json()
  )

  return {
    props: { post },
    // 当请求到来时,Next.js 会使缓存失效,
    // 但最多每 60 秒一次。
    revalidate: 60,
  }
}

export default function Page({ post }) {
  return (
    <main>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </main>
  )
}

此示例的工作方式如下:

  1. 在 next build 期间,会生成所有已知的博客文章
  2. 对这些页面的所有请求(例如 /blog/1)都会被缓存并即时响应
  3. 过了 60 秒后,下一个请求仍会返回缓存的(现已过时的)页面
  4. 缓存失效,页面新版本开始在后台生成
  5. 生成成功后,下一个请求将返回更新后的页面,并将其缓存以供后续请求使用
  6. 如果请求 /blog/26 且该文章存在,则该页面将按需生成。可以通过使用不同的 fallback 值来更改此行为。但是,如果文章不存在,则返回 404。

参考#

路由段配置#

函数#

函数#

示例#

基于时间的再验证#

此示例在 /blog 上获取并显示博客文章列表。一小时后,下一位访问者仍会立即收到缓存的(过时的)页面版本,以获得快速响应。同时,Next.js 会在后台触发新版本的再生成。新版本成功生成后,会替换缓存版本,后续访问者将收到更新后的内容。

app/blog/page.tsx
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>Blog Posts</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </main>
  )
}
app/blog/page.js
export const revalidate = 3600 // 每小时失效一次

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

我们建议设置较长的再验证时间。例如,设置为 1 小时而不是 1 秒。如果需要更高的精度,请考虑使用按需再验证。如果需要实时数据,请考虑切换到动态渲染。

使用 revalidatePath 进行按需再验证#

要获得更精确的再验证方法,可以使用 revalidatePath 函数按需使缓存页面失效。

例如,此 Server Action 会在添加新文章后调用。无论你在 Server Component 中如何检索数据(使用 fetch 还是连接数据库),这都会使整个路由的缓存失效。对该路由的下一个请求将触发再生成并提供新数据,随后这些数据会被缓存以供后续请求使用。

注意: revalidatePath 会使缓存条目失效,但再生成发生在下一个请求时。如果你希望立即主动重新生成缓存条目而不是等待下一个请求,可以使用 Pages Router 的 res.revalidate 方法。我们正在努力添加新方法,为 App Router 提供主动再生成能力。

app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createPost() {
  // 使 /posts 路由的缓存失效
  revalidatePath('/posts')
}
app/actions.js
'use server'

import { revalidatePath } from 'next/cache'

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

查看演示并探索源代码。

使用 revalidateTag 进行按需再验证#

对于大多数用例,建议重新验证整个路径。如果需要更细粒度的控制,可以使用 revalidateTag 函数。例如,你可以为单个 fetch 调用添加标签:

app/blog/page.tsx
export default async function Page() {
  const data = await fetch('https://api.vercel.app/blog', {
    next: { tags: ['posts'] },
  })
  const posts = await data.json()
  // ...
}
app/blog/page.js
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:

app/blog/page.tsx
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()
  // ...
}
app/blog/page.js
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()
  // ...
}

然后你可以在 Server Actions 或 Route Handler 中使用 revalidateTag:

app/actions.ts
'use server'

import { revalidateTag } from 'next/cache'

export async function createPost() {
  // 使所有带有 'posts' 标签的数据失效
  revalidateTag('posts', 'max')
}
app/actions.js
'use server'

import { revalidateTag } from 'next/cache'

export async function createPost() {
  // 使所有带有 'posts' 标签的数据失效
  revalidateTag('posts', 'max')
}

使用 res.revalidate() 进行按需验证#

要获得更精确的再验证方法,可以使用 res.revalidate 从 API Router 按需生成新页面。

例如,可以在 /api/revalidate?secret=<token> 调用此 API Route 来重新验证指定的博客文章。创建一个只有你的 Next.js 应用知道的密钥令牌。此密钥将用于防止未经授权访问再验证 API Route。

pages/api/revalidate.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // 检查密钥以确认这是有效请求
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  try {
    // 这应该是实际路径,而不是重写后的路径
    // 例如对于 "/posts/[id]",这里应该是 "/posts/1"
    await res.revalidate('/posts/1')
    return res.json({ revalidated: true })
  } catch (err) {
    // 如果出现错误,Next.js 将继续
    // 显示上一次成功生成的页面
    return res.status(500).send('Error revalidating')
  }
}
pages/api/revalidate.js
export default async function handler(req, res) {
  // 检查密钥以确认这是有效请求
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  try {
    // 这应该是实际路径,而不是重写后的路径
    // 例如对于 "/posts/[id]",这里应该是 "/posts/1"
    await res.revalidate('/posts/1')
    return res.json({ revalidated: true })
  } catch (err) {
    // 如果出现错误,Next.js 将继续
    // 显示上一次成功生成的页面
    return res.status(500).send('Error revalidating')
  }
}

如果使用按需再验证,则无需在 getStaticProps 中指定 revalidate 时间。Next.js 将使用默认值 false(不再验证),仅在调用 res.revalidate() 时按需重新验证页面。

处理未捕获的异常#

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

如果 getStaticProps 在处理后台再生成时出错,或者你手动抛出错误,上一次成功生成的页面将继续显示。在下一个后续请求中,Next.js 将重试调用 getStaticProps。

pages/blog/[id].tsx
import type { GetStaticProps } from 'next'

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

interface Props {
  post: Post
}

export const getStaticProps: GetStaticProps<Props> = async ({
  params,
}: {
  params: { id: string }
}) => {
  // 如果此请求抛出未捕获的错误,Next.js 将
  // 不会使当前显示的页面失效,并在下一个请求时
  // 重试 getStaticProps。
  const res = await fetch(`https://api.vercel.app/blog/${params.id}`)
  const post: Post = await res.json()

  if (!res.ok) {
    // 如果出现服务器错误,你可能希望
    // 抛出错误而不是返回,这样缓存就不会被更新,
    // 直到下一次成功的请求为止。
    throw new Error(`Failed to fetch posts, received status ${res.status}`)
  }

  return {
    props: { post },
    // 当请求到来时,Next.js 会使缓存失效,
    // 但最多每 60 秒一次。
    revalidate: 60,
  }
}
pages/blog/[id].jsx
export async function getStaticProps({ params }) {
  // 如果此请求抛出未捕获的错误,Next.js 将
  // 不会使当前显示的页面失效,并在下一个请求时
  // 重试 getStaticProps。
  const res = await fetch(`https://api.vercel.app/blog/${params.id}`)
  const post = await res.json()

  if (!res.ok) {
    // 如果出现服务器错误,你可能希望
    // 抛出错误而不是返回,这样缓存就不会被更新,
    // 直到下一次成功的请求为止。
    throw new Error(`Failed to fetch posts, received status ${res.status}`)
  }

  return {
    props: { post },
    // 当请求到来时,Next.js 会使缓存失效,
    // 但最多每 60 秒一次。
    revalidate: 60,
  }
}

自定义缓存位置#

如果希望将缓存的页面和数据持久化到持久存储,或在 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 运行时(默认)时受支持。
  • 创建静态导出时不支持 ISR。
  • 如果预渲染路由中有多个 fetch 请求,且每个请求的 revalidate 频率不同,则 ISR 将使用最短的时间。不过,缓存仍会遵守这些再验证频率。
  • 如果路由中使用的任何 fetch 请求的 revalidate 时间为 0,或显式设置了 no-store,则该路由将被动态渲染。
  • 按需 ISR 请求不会执行 Proxy,这意味着 Proxy 中的任何路径重写或逻辑都不会被应用。请确保重新验证的是准确的路径。例如,使用 /post/1 而不是重写后的 /post-1。
  • 运行多个实例时,默认的文件系统缓存是按实例划分的。按需再验证只会使接收调用的那个实例失效。使用共享的自定义缓存处理程序来跨实例协调。有关完整架构,请参阅再验证的工作原理。
  • 后台再生成(stale-while-revalidate)在接收触发请求的实例上运行。在按请求计费的平台上,这些后台工作会算作额外计算。
  • 可以使用 x-nextjs-cache 响应标头来观察缓存行为。取值包括 HIT(从缓存提供)、STALE(从缓存提供,正在后台再验证)、MISS(不在缓存中,重新渲染)或 REVALIDATED(通过按需再验证重新生成)。
  • ISR 仅在使用 Node.js 运行时(默认)时受支持。
  • 创建静态导出时不支持 ISR。
  • 按需 ISR 请求不会执行 Proxy,这意味着 Proxy 中的任何路径重写或逻辑都不会被应用。请确保重新验证的是准确的路径。例如,使用 /post/1 而不是重写后的 /post-1。

平台支持#

部署选项是否支持
Node.js 服务器是
Docker 容器是
静态导出否
适配器视平台而定

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

版本历史#

版本变更
v14.1.0自定义 cacheHandler 已稳定。
v13.0.0引入 App Router。
v12.2.0Pages Router:按需 ISR 已稳定
v12.0.0Pages Router:新增机器人感知的 ISR 回退。
v9.5.0Pages Router:引入稳定的 ISR。
Next.js 中文网