如何实现增量静态再生(ISR)
了解如何使用增量静态再生(ISR)在运行时创建或更新静态页面。
<details> <summary>示例</summary>
</details>
小知识:本指南介绍不使用 Cache Components 的 ISR。如果你正在使用
cacheComponents,请改为参阅使用 Cache Components 的 ISR。
增量静态再生成(ISR)使你能够:
- 无需重建整个站点即可更新静态内容
- 通过为大多数请求提供预渲染的静态页面来降低服务器负载
- 确保自动为页面添加适当的
cache-control标头 - 处理大量内容页面而无需漫长的
next build时间
以下是一个最小示例:
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>
)
}// 当请求到来时,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>
)
}此示例的工作方式如下:
generateStaticParams通过返回要预渲染的文章列表,为动态路由启用 ISR- 在
next build期间,会为每篇文章预渲染一个页面 - 对这些页面的所有请求(例如
/blog/1)都会被缓存并即时响应 - 过了 60 秒后,下一个请求仍会返回缓存的(现已过时的)页面
- 缓存失效,页面新版本开始在后台生成
- 生成成功后,下一个请求将返回更新后的页面,并将其缓存以供后续请求使用
- 如果请求
/blog/26且该文章存在,则该页面将按需生成。可以通过使用不同的 dynamicParams 值来更改此行为。但是,如果文章不存在,则返回 404。
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>
)
}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>
)
}此示例的工作方式如下:
- 在
next build期间,会生成所有已知的博客文章 - 对这些页面的所有请求(例如
/blog/1)都会被缓存并即时响应 - 过了 60 秒后,下一个请求仍会返回缓存的(现已过时的)页面
- 缓存失效,页面新版本开始在后台生成
- 生成成功后,下一个请求将返回更新后的页面,并将其缓存以供后续请求使用
- 如果请求
/blog/26且该文章存在,则该页面将按需生成。可以通过使用不同的 fallback 值来更改此行为。但是,如果文章不存在,则返回 404。
参考#
示例#
基于时间的再验证#
此示例在 /blog 上获取并显示博客文章列表。一小时后,下一位访问者仍会立即收到缓存的(过时的)页面版本,以获得快速响应。同时,Next.js 会在后台触发新版本的再生成。新版本成功生成后,会替换缓存版本,后续访问者将收到更新后的内容。
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>
)
}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 提供主动再生成能力。
'use server'
import { revalidatePath } from 'next/cache'
export async function createPost() {
// 使 /posts 路由的缓存失效
revalidatePath('/posts')
}'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()
// ...
}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()
// ...
}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:
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost() {
// 使所有带有 'posts' 标签的数据失效
revalidateTag('posts', 'max')
}'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。
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')
}
}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。
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,
}
}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 选项的信息。
module.exports = {
logging: {
fetches: {
fullUrl: true,
},
},
}验证生产环境中的正确行为#
要验证你的页面在生产环境中被正确缓存和再验证,可以在本地运行 next build,然后运行 next start 来启动生产环境的 Next.js 服务器,以此进行测试。
这使你可以测试 ISR 在生产环境中的行为。要进行进一步的调试,请将以下环境变量添加到 .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.0 | Pages Router:按需 ISR 已稳定 |
v12.0.0 | Pages Router:新增机器人感知的 ISR 回退。 |
v9.5.0 | Pages Router:引入稳定的 ISR。 |