React / 系统课时
按标签刷新缓存
按标签刷新缓存
当首页、列表页和后台面板都读取同一份数据时,逐个调用 revalidatePath 很快会变得脆弱。缓存标签把“哪些页面”转换成“哪类数据”:先给缓存项打上稳定标签,数据变化后按标签失效,所有依赖这份数据的页面都能共享同一套刷新规则。
学习目标
- 能给服务端缓存数据分配稳定、可复用的标签
- 能使用
revalidateTag刷新多个页面共享的数据 - 能区分
revalidateTag与updateTag的一致性语义和适用位置
标签把刷新范围绑定到数据
标签不是路由名,而是缓存数据的逻辑身份。假设 /、/posts 和 /dashboard 都读取文章列表,只要这些缓存项都带有 posts 标签,一次标签失效就能同时覆盖它们,不需要知道究竟有多少页面消费了这份数据。

这种模型尤其适合文章列表、商品目录、用户资料等被多个路由复用的数据。标签值区分大小写,应保持短小稳定;不要把完整 URL 或频繁变化的展示条件直接当作标签。
给缓存请求分配标签
对于服务端 fetch,可以通过 next.tags 关联标签。当前 fetch 默认并不保证进入持久 Data Cache,因此下面同时使用 cache: 'force-cache' 明确启用缓存。
export type Post = {
id: number
title: string
}
export async function getPosts(): Promise<Post[]> {
const response = await fetch('https://api.vercel.app/blog', {
cache: 'force-cache',
next: { tags: ['posts'] },
})
if (!response.ok) {
throw new Error(`Failed to load posts: ${response.status}`)
}
return response.json()
}预期结果
首次调用从远端获取文章并写入服务端数据缓存。
后续相同请求可复用缓存,并且该缓存项可以通过 posts 标签进行按需失效。getPosts() 可以同时被多个 Server Component 调用;只要它们复用的是带 posts 标签的缓存项,后续刷新就不需要逐个维护页面路径。
使用 revalidateTag 标记共享数据过期
revalidateTag 可以在 Server Function 和 Route Handler 中调用。推荐的 max profile 使用 stale-while-revalidate:调用后先把标签标记为过期,下一次有页面访问这份数据时触发重新验证,同时可先返回旧内容,避免所有关联页面同时阻塞刷新。
下面创建一个可直接放入 app/api/revalidate-posts/route.ts 的 Route Handler:
import { revalidateTag } from 'next/cache'
export async function POST() {
// posts 标签下的缓存统一进入待重新验证状态。
revalidateTag('posts', 'max')
return Response.json({
revalidated: true,
tag: 'posts',
})
}调用接口:
curl -i -X POST http://localhost:<PORT>/api/revalidate-posts预期输出
HTTP/1.1 200 OK
...
{"revalidated":true,"tag":"posts"}<PORT> 代表实际开发服务器端口。接口返回成功只表示标签已被标记;真正的数据重新获取由之后对带该标签缓存的访问触发。
需要立即读到自己刚写的数据时
revalidateTag(..., 'max') 优先保证响应速度,允许下一次请求先看到旧值再后台刷新。如果用户在 Server Action 中刚保存一篇文章,并要求跳转后立刻看到自己的修改,应使用 updateTag('posts')。它只允许在 Server Action 中调用,并让下一次读取等待新数据。
因此可以用一个简单判断来选 API:页面范围明确就用 revalidatePath;多个页面共享同一数据且允许短暂旧值就用 revalidateTag;Server Action 写入后必须立即读到新值就用 updateTag。 标签设计得越贴近业务数据边界,后续新增页面时越不需要修改失效逻辑。