unstable_expirePath

unstable_expirePath 允许你按需清除特定路径的缓存数据。

¥unstable_expirePath allows you to purge cached data on-demand for a specific path.

很高兴知道：

¥Good to know:

unstable_expirePath 在 Node.js 和 Edge 运行时中均可用。

¥unstable_expirePath is available in both Node.js and Edge runtimes.

unstable_expirePath 仅在下次访问包含的路径时使缓存无效。这意味着使用动态路由段调用 unstable_expirePath 不会立即触发许多过期。仅当下次访问该路径时才会发生失效。

¥unstable_expirePath only invalidates the cache when the included path is next visited. This means calling unstable_expirePath with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.

目前，unstable_expirePath 在服务器操作中使用时会使客户端路由缓存中的所有路由失效。此行为是临时的，将来会更新以仅适用于特定路径。

¥Currently, unstable_expirePath invalidates all the routes in the client-side Router Cache when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.

使用 unstable_expirePath 只会使服务器端路由缓存中的特定路径无效。

¥Using unstable_expirePath invalidates only the specific path in the server-side Route Cache.

参考

¥Reference

参数

¥Parameters

unstable_expirePath(path: string, type?: 'page' | 'layout'): void;

path：表示与要过期的数据关联的文件系统路径的字符串（例如 /product/[slug]/page），或文字路由段（例如 /product/123）。必须少于 1024 个字符。该值区分大小写。

¥path: Either a string representing the filesystem path associated with the data you want to expire (for example, /product/[slug]/page), or the literal route segment (for example, /product/123). Must be less than 1024 characters. This value is case-sensitive.
type：（可选）'page' 或 'layout' 字符串用于更改要过期的路径类型。如果 path 包含动态段（例如 /product/[slug]/page），则需要此参数。如果路径指的是文字路由段，例如动态页面的 /product/1（例如 /product/[slug]/page），则不应提供 type。

¥type: (optional) 'page' or 'layout' string to change the type of path to expire. If path contains a dynamic segment (for example, /product/[slug]/page), this parameter is required. If path refers to the literal route segment, e.g., /product/1 for a dynamic page (e.g., /product/[slug]/page), you should not provide type.

¥Returns

unstable_expirePath 不返回值。

¥unstable_expirePath does not return a value.

示例

¥Examples

使特定 URL 过期

¥Expiring a specific URL

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

这将在下次访问页面时清除一个特定 URL 的缓存。

¥This will purge the cache for one specific URL on the next page visit.

使页面路径过期

¥Expiring a page path

import { unstable_expirePath } from 'next/cache'
unstable_expirePath('/blog/[slug]', 'page')
// or with route groups
unstable_expirePath('/(main)/blog/[slug]', 'page')

这将在下次访问页面时清除与提供的 page 文件匹配的任何 URL 的缓存。这不会使特定页面下方的页面失效。例如，/blog/[slug] 不会使 /blog/[slug]/[author] 无效。

¥This will purge the cache any URL that matches the provided page file on the next page visit. This will not invalidate pages beneath the specific page. For example, /blog/[slug] won't invalidate /blog/[slug]/[author].

使布局路径过期

¥Expiring a layout path

import { unstable_expirePath } from 'next/cache'
unstable_expirePath('/blog/[slug]', 'layout')
// or with route groups
unstable_expirePath('/(main)/post/[slug]', 'layout')

这将清除下次访问页面时与提供的 layout 文件匹配的任何 URL 上的缓存。这将导致具有相同布局的下方页面在下次访问时重新验证。例如，在上述情况下，/blog/[slug]/[another] 也会在下次访问时重新验证。

¥This will purge the cache on any URL that matches the provided layout file on the next page visit. This will cause pages beneath with the same layout to revalidate on the next visit. For example, in the above case, /blog/[slug]/[another] would also revalidate on the next visit.

使所有数据过期

¥Expiring all data

import { unstable_expirePath } from 'next/cache'

unstable_expirePath('/', 'layout')

这将在下次访问页面时清除数据缓存。

¥This will purge the Data Cache on the next page visit.

服务器动作

¥Server Action

你可以在服务器操作中调用 unstable_expirePath：

¥You can call unstable_expirePath in a Server Action:

'use server'

import { unstable_expirePath } from 'next/cache'

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

路由处理程序

¥Route Handler

你可以在路由处理程序中调用 unstable_expirePath：

¥You can call unstable_expirePath in a Route Handler:

import { unstable_expirePath } from 'next/cache'
import type { NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const path = request.nextUrl.searchParams.get('path')

  if (path) {
    unstable_expirePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }

  return Response.json({
    expired: false,
    now: Date.now(),
    message: 'Missing path to expire',
  })
}

import { unstable_expirePath } from 'next/cache'

export async function GET(request) {
  const path = request.nextUrl.searchParams.get('path')

  if (path) {
    unstable_expirePath(path)
    return Response.json({ expired: true, now: Date.now() })
  }

  return Response.json({
    expired: false,
    now: Date.now(),
    message: 'Missing path to expire',
  })
}

参考​

参数​

返回​

示例​

使特定 URL 过期​

使页面路径过期​

使布局路径过期​

使所有数据过期​

服务器动作​

路由处理程序​

参考

参数

返回

示例