NNext.js 中文网 GitHub

revalidatePath

revalidatePath 函数的 API 参考。

revalidatePath 让你可以针对特定路径按需使缓存数据失效。

用法#

revalidatePath 可在 Server Function 和 Route Handler 中调用。

revalidatePath 不能在 Client Component 或 Proxy 中调用,因为它仅在服务端环境中有效。

小知识:

  • Server Function:立即更新 UI(如果正在查看受影响的路径)。目前,它还会使所有之前访问过的页面在再次导航到时刷新。此行为是临时的,将来会更新为仅应用于特定路径。
  • Route Handler:标记该路径以进行重新验证。重新验证会在下次访问指定路径时完成。这意味着使用动态路由片段调用 revalidatePath 不会立即触发大量重新验证。失效只会在下次访问该路径时发生。

参数#

tsx
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 失效:
app/api/data/route.ts
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 的重写:

next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: '/blog',
        destination: '/news',
      },
    ]
  },
}

要重新验证此页面,请使用目标路径:

ts
// 正确:使用目标路径
revalidatePath('/news')

// 错误:源路径不会匹配缓存条目
revalidatePath('/blog')

这是因为 revalidatePath 基于路由文件结构操作,而不是用户可见的 URL。缓存条目根据渲染它们的路由文件打标签。

与 revalidateTag 和 updateTag 的关系#

revalidatePath、revalidateTag 和 updateTag 用途不同:

  • revalidatePath:使特定页面或布局路径失效
  • revalidateTag:将带有特定标签的数据标记为过期(stale)。适用于所有使用这些标签的页面
  • updateTag:使带有特定标签的数据过期。适用于所有使用这些标签的页面

调用 revalidatePath 时,只有指定路径在下次访问时获得新数据。使用相同数据标签的其他页面将继续提供缓存数据,直到这些特定标签也被重新验证:

tsx
// 页面 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 是互补的基础方法,常在工具函数中一起使用,以确保整个应用的数据一致性:

ts
'use server'

import { revalidatePath, updateTag } from 'next/cache'

export async function updatePost() {
  await updatePostInDatabase()

  revalidatePath('/blog') // 刷新博客页面
  updateTag('posts') // 刷新所有使用 'posts' 标签的页面
}

此模式可确保特定页面和使用相同数据的其他页面保持一致。

示例#

重新验证特定路径#

ts
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/post-1')

这会使某个特定路径失效,以便在下一次页面访问时重新验证。

重新验证 Page 路径#

ts
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'page')
// 或使用路由组
revalidatePath('/(main)/blog/[slug]', 'page')

这会使与提供的 page 文件匹配的任何路径失效,以便在下一次页面访问时重新验证。这不会使该特定页面下的页面失效。例如,/blog/[slug] 不会使 /blog/[slug]/[author] 失效。

重新验证 Layout 路径#

ts
import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'layout')
// 或使用路由组
revalidatePath('/(main)/post/[slug]', 'layout')

这会使与提供的 layout 文件匹配的任何路径失效,以便在下一次页面访问时重新验证。这会导致使用相同布局的下级页面在下次访问时失效并重新验证。例如,在上述情况下,/blog/[slug]/[another] 也会在下次访问时失效并重新验证。

重新验证所有数据#

ts
import { revalidatePath } from 'next/cache'

revalidatePath('/', 'layout')

这将清除客户端缓存(Client Cache),并使所有缓存数据失效,以便在下一次页面访问时重新验证。

Server Function#

app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export default async function submit() {
  await submitForm()
  revalidatePath('/')
}

Route Handler#

app/api/revalidate/route.ts
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',
  })
}
app/api/revalidate/route.js
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',
  })
}
Next.js 中文网