React / 系统课时
按路径刷新缓存
按路径刷新缓存
数据已经写入成功,但页面仍可能继续使用旧的服务端缓存。按路径刷新解决的是“这次变更影响了哪个页面或路由树”的问题:数据写入后调用 revalidatePath,让指定路径在合适的时机重新读取数据,而不是粗暴地清空整个应用的缓存。
学习目标
- 掌握
revalidatePath的调用位置和失效范围 - 能根据具体 URL、动态路由模式和布局选择正确参数
- 能在 Server Action 完成写入后刷新受影响页面并验证结果
按路径失效的工作方式
revalidatePath(path, type?) 只能在服务端环境调用,例如 Server Action、其他 Server Function 或 Route Handler。它针对的是路由路径:你知道哪一个页面受本次变更影响,就直接让这个页面或一组匹配页面重新验证。
在 Server Action 中,如果用户正停留在受影响页面,新的服务端结果可以随本次交互更新到界面;在 Route Handler 中调用时,目标路径会先被标记,真正的重新验证发生在下一次访问该路径时。

选择具体路径还是路由模式
刷新一个确定页面时传具体 URL,例如 /posts/42,不需要第二个参数。要刷新动态路由模式,则传路由文件对应的模式,并显式指定 page 或 layout。
import { revalidatePath } from 'next/cache'
// 只刷新一个确定页面
revalidatePath('/posts/42')
// 刷新所有匹配 app/posts/[slug]/page.tsx 的页面
revalidatePath('/posts/[slug]', 'page')
// 刷新该布局以及它下面的页面和嵌套布局
revalidatePath('/dashboard', 'layout')这是 API 片段示例,调用本身没有返回值。验证时分别访问目标路径:具体 URL 只影响该页面;动态模式会覆盖所有匹配页面;layout 的范围更大,会连同该布局下的子树一起重新验证。
在数据写入后刷新页面
最常见的位置是 Server Action:先完成持久化,再刷新受影响路径。下面假设项目已经提供 updatePostInDatabase 数据访问函数,因此属于片段示例;关键顺序是“写入成功 → 刷新路径 → 跳转”。
'use server'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { updatePostInDatabase } from '@/lib/posts'
export async function updatePost(id: string, formData: FormData) {
const title = String(formData.get('title') ?? '').trim()
if (!title) {
throw new Error('title is required')
}
// 只有数据库写入成功后,才让对应详情页失效。
await updatePostInDatabase(id, { title })
revalidatePath(`/posts/${id}`)
redirect(`/posts/${id}`)
}预期结果
提交成功后跳转到 /posts/<ID>。
该详情页读取并显示更新后的标题;未匹配的其他路径不会因为这次 revalidatePath 自动失效。其中 <ID> 代表真实文章 ID,实际值由业务数据决定。如果列表页 /posts 也显示了被修改的标题,那么还应额外刷新列表路径,或者改用能够覆盖共享数据的标签失效策略。
避免把路径刷新当成万能清缓存
revalidatePath('/posts/42') 只处理这个路径的缓存一致性。如果 /posts、/dashboard 和首页都复用了同一份文章数据,它们不会因为详情页被刷新就自动全部同步。此时应根据数据关系选择 revalidateTag 或 updateTag,而不是枚举越来越多的路径。
客户端的 router.refresh() 也不是替代品:它会重新请求当前路由并更新 Server Components,但不会主动使服务端持久缓存失效。数据变更后的可靠顺序仍然是先更新数据源,再用服务端缓存 API 声明哪些缓存需要失效。