revalidatePath
revalidatePath 函数的 API 参考。
revalidatePath 让你可以针对特定路径按需使缓存数据失效。
用法#
revalidatePath 可在 Server Function 和 Route Handler 中调用。
revalidatePath 不能在 Client Component 或 Proxy 中调用,因为它仅在服务端环境中有效。
小知识:
- Server Function:立即更新 UI(如果正在查看受影响的路径)。目前,它还会使所有之前访问过的页面在再次导航到时刷新。此行为是临时的,将来会更新为仅应用于特定路径。
- Route Handler:标记该路径以进行重新验证。重新验证会在下次访问指定路径时完成。这意味着使用动态路由片段调用
revalidatePath不会立即触发大量重新验证。失效只会在下次访问该路径时发生。
参数#
revalidatePath(path: string, type?: 'page' | 'layout'): void;path:表示路由文件结构的字符串。它可以是字面路径(如/product/123),也可以是带动态片段的路由模式(如/product/[slug])。不要追加/page或/layout,请使用type参数。长度不得超过 1024 个字符。该值区分大小写。无论trailingSlash配置如何,都无需包含尾部斜杠。type:(可选)'page'或'layout'字符串,用于更改要重新验证的路径类型。如果path包含动态片段(例如/product/[slug]),则此参数为必填。如果path是字面路径(如/product/1),请省略type。
要刷新单个页面,请使用字面路径。要刷新所有匹配的页面,请使用路由模式加 type。
返回值#
revalidatePath 不返回任何值。
可以使哪些内容失效#
path 参数可以指向页面、布局或 Route Handler:
- 页面:使特定页面失效
- 布局:使该布局(该片段的
layout.tsx)、其下所有嵌套布局以及这些布局下的所有页面失效 - Route Handler:使 Route Handler 内访问的缓存数据失效。例如
revalidatePath("/api/data")会使以下 GET handler 失效:
export async function GET() {
const data = await fetch('https://api.vercel.app/blog', {
cache: 'force-cache',
})
return Response.json(await data.json())
}将 revalidatePath 与重写一起使用#
使用重写时,必须传递目标(destination)路径(实际的路由文件位置),而不是浏览器地址栏中显示的源(source)路径。
例如,如果你有一个从 /blog 到 /news 的重写:
module.exports = {
async rewrites() {
return [
{
source: '/blog',
destination: '/news',
},
]
},
}要重新验证此页面,请使用目标路径:
// 正确:使用目标路径
revalidatePath('/news')
// 错误:源路径不会匹配缓存条目
revalidatePath('/blog')这是因为 revalidatePath 基于路由文件结构操作,而不是用户可见的 URL。缓存条目根据渲染它们的路由文件打标签。
与 revalidateTag 和 updateTag 的关系#
revalidatePath、revalidateTag 和 updateTag 用途不同:
revalidatePath:使特定页面或布局路径失效revalidateTag:将带有特定标签的数据标记为过期(stale)。适用于所有使用这些标签的页面updateTag:使带有特定标签的数据过期。适用于所有使用这些标签的页面
调用 revalidatePath 时,只有指定路径在下次访问时获得新数据。使用相同数据标签的其他页面将继续提供缓存数据,直到这些特定标签也被重新验证:
// 页面 A:/blog
const posts = await fetch('https://api.vercel.app/blog', {
next: { tags: ['posts'] },
})
// 页面 B:/dashboard
const recentPosts = await fetch('https://api.vercel.app/blog?limit=5', {
next: { tags: ['posts'] },
})调用 revalidatePath('/blog') 后:
- 页面 A(/blog):显示新数据(页面已重新渲染)
- 页面 B(/dashboard):仍显示过期数据(缓存标签 'posts' 未失效)
了解 revalidateTag 和 updateTag 的区别。
构建重新验证工具函数#
revalidatePath 和 updateTag 是互补的基础方法,常在工具函数中一起使用,以确保整个应用的数据一致性:
'use server'
import { revalidatePath, updateTag } from 'next/cache'
export async function updatePost() {
await updatePostInDatabase()
revalidatePath('/blog') // 刷新博客页面
updateTag('posts') // 刷新所有使用 'posts' 标签的页面
}此模式可确保特定页面和使用相同数据的其他页面保持一致。
示例#
重新验证特定路径#
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/post-1')这会使某个特定路径失效,以便在下一次页面访问时重新验证。
重新验证 Page 路径#
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'page')
// 或使用路由组
revalidatePath('/(main)/blog/[slug]', 'page')这会使与提供的 page 文件匹配的任何路径失效,以便在下一次页面访问时重新验证。这不会使该特定页面下的页面失效。例如,/blog/[slug] 不会使 /blog/[slug]/[author] 失效。
重新验证 Layout 路径#
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'layout')
// 或使用路由组
revalidatePath('/(main)/post/[slug]', 'layout')这会使与提供的 layout 文件匹配的任何路径失效,以便在下一次页面访问时重新验证。这会导致使用相同布局的下级页面在下次访问时失效并重新验证。例如,在上述情况下,/blog/[slug]/[another] 也会在下次访问时失效并重新验证。
重新验证所有数据#
import { revalidatePath } from 'next/cache'
revalidatePath('/', 'layout')这将清除客户端缓存(Client Cache),并使所有缓存数据失效,以便在下一次页面访问时重新验证。
Server Function#
'use server'
import { revalidatePath } from 'next/cache'
export default async function submit() {
await submitForm()
revalidatePath('/')
}Route Handler#
import { revalidatePath } from 'next/cache'
import type { NextRequest } from 'next/server'
export async function GET(request: NextRequest) {
const path = request.nextUrl.searchParams.get('path')
if (path) {
revalidatePath(path)
return Response.json({ revalidated: true, now: Date.now() })
}
return Response.json({
revalidated: false,
now: Date.now(),
message: 'Missing path to revalidate',
})
}import { revalidatePath } from 'next/cache'
export async function GET(request) {
const path = request.nextUrl.searchParams.get('path')
if (path) {
revalidatePath(path)
return Response.json({ revalidated: true, now: Date.now() })
}
return Response.json({
revalidated: false,
now: Date.now(),
message: 'Missing path to revalidate',
})
}