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

示例

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

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

以下是一个最小示例：

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) },
  }))

  // 我们仅在构建时预渲染这些路径。
  // { fallback: 'blocking' } 会在路径不存在时按需服务端渲染页面。
  return { paths, fallback: false }
}

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>
  )
}

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 },
  }))

  // 我们仅在构建时预渲染这些路径。
  // { fallback: false } 表示其他路由应返回 404。
  return { paths, fallback: false }
}

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>
  )
}

这个示例的工作原理：

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

参考

函数

示例

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

对于更精确的重新验证方法，可以使用 res.revalidate 从 API 路由按需生成新页面。

例如，可以调用 /api/revalidate?secret=<token> 这个 API 路由来重新验证给定的博客文章。创建一个只有您的 Next.js 应用知道的秘密令牌。此秘密将用于防止未经授权访问重新验证 API 路由。

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: '无效令牌' })
  }

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

export default async function handler(req, res) {
  // 检查秘密以确认这是一个有效的请求
  if (req.query.secret !== process.env.MY_SECRET_TOKEN) {
    return res.status(401).json({ message: '无效令牌' })
  }

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

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

处理未捕获的异常

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

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(`获取文章失败，收到状态 ${res.status}`)
  }

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

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(`获取文章失败，收到状态 ${res.status}`)
  }

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

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。
按需 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。

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

参考

函数

示例

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

处理未捕获的异常

自定义缓存位置

故障排除

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

验证生产环境行为

注意事项

平台支持

版本历史

On this page