跳到内容
API 参考函数cacheLife

cacheLife

此功能目前在 canary 频道中可用，可能会发生变化。通过升级 Next.js 尝试使用，并在 GitHub 上分享您的反馈。

cacheLife 函数用于设置函数或组件的缓存生命周期。它应与 use cache 指令一起使用，并在函数或组件的作用域内使用。

用法

要使用 cacheLife，请在你的 next.config.js 文件中启用 dynamicIO 标志

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}
 
export default nextConfig

然后，在函数或组件的作用域内导入并调用 cacheLife 函数

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

参考

默认缓存配置

Next.js 提供了一组基于不同时间刻度的命名缓存配置。如果在 cacheLife 函数中没有与 use cache 指令一起指定缓存配置，Next.js 将自动应用“default”缓存配置。

但是，我们建议在使用 use cache 指令时始终添加缓存配置，以显式定义缓存行为。

配置过时时间重新验证过期时间描述
default未定义15 分钟INFINITE_CACHE默认配置，适用于不需要频繁更新的内容
seconds未定义1 秒1 分钟适用于需要接近实时的快速变化内容
minutes5 分钟1 分钟1 小时适用于在一小时内频繁更新的内容
hours5 分钟1 小时1 天适用于每天更新但可以略有过时的内容
days5 分钟1 天1 周适用于每周更新但可以过时一天的内容
weeks5 分钟1 周1 个月适用于每月更新但可以过时一周的内容
max5 分钟1 个月INFINITE_CACHE适用于非常稳定的、很少需要更新的内容

用于引用缓存配置的字符串值不具有内在含义；相反，它们用作语义标签。这使您可以更好地理解和管理代码库中缓存的内容。

自定义缓存配置

你可以通过将自定义缓存配置添加到你的 next.config.ts 文件中的 cacheLife 选项来配置它们。

缓存配置是包含以下属性的对象

属性值描述要求
stalenumber客户端应缓存值而不检查服务器的持续时间。可选
revalidatenumber缓存应在服务器上刷新的频率；在重新验证时可能会提供过时的值。可选
expirenumber值在切换到动态获取之前可以保持过时的最长持续时间；必须长于 revalidate。可选 - 必须长于 revalidate

“stale” 属性与 staleTimes 设置不同，因为它专门控制客户端路由器缓存。虽然 staleTimes 是影响动态和静态数据的所有实例的全局设置，但 cacheLife 配置允许你定义每个函数或每个路由的“stale”时间。

须知：“stale” 属性不设置 Cache-control: max-age 标头。它而是控制客户端路由器缓存。

示例

定义可重用的缓存配置

你可以通过在你的 next.config.ts 文件中定义可重用的缓存配置。选择一个适合你的用例的名称，并为 stale、revalidate 和 expire 属性设置值。你可以根据需要创建任意数量的自定义缓存配置。每个配置都可以通过其名称作为传递给 cacheLife 函数的字符串值来引用。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 days
        revalidate: 60 * 60 * 24, // 1 day
        expire: 60 * 60 * 24 * 14, // 14 days
      },
    },
  },
}
 
module.exports = nextConfig

上面的示例缓存 14 天，每天检查更新，并在 14 天后过期缓存。然后你可以在整个应用程序中通过其名称引用此配置

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

覆盖默认缓存配置

虽然默认缓存配置提供了一种有用的方式来考虑任何给定部分的可缓存输出的新鲜度或过时程度，但你可能更喜欢不同的命名配置，以便更好地与你的应用程序缓存策略保持一致。

你可以通过创建与默认配置同名的新配置来覆盖默认的命名缓存配置。

下面的示例展示了如何覆盖默认的“days”缓存配置

next.config.ts
const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 hour
        revalidate: 900, // 15 minutes
        expire: 86400, // 1 day
      },
    },
  },
}
 
module.exports = nextConfig

内联定义缓存配置

对于特定用例，你可以通过将对象传递给 cacheLife 函数来设置自定义缓存配置

app/page.tsx
'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export default async function Page() {
  cacheLife({
    stale: 3600, // 1 hour
    revalidate: 900, // 15 minutes
    expire: 86400, // 1 day
  })
 
  return <div>Page</div>
}

此内联缓存配置将仅应用于创建它的函数或文件。如果你想在整个应用程序中重用相同的配置，你可以将配置添加到 next.config.ts 文件的 cacheLife 属性中。

use cache 和 cacheLife 的嵌套使用

在同一路由或组件树中定义多个缓存行为时，如果内部缓存指定了自己的 cacheLife 配置，则外部缓存将遵循其中最短的缓存持续时间。这仅在外部缓存没有定义自己的显式 cacheLife 配置时适用。

例如，如果你将 use cache 指令添加到你的页面，而不指定缓存配置，则默认缓存配置将隐式应用 (cacheLife(”default”))。如果导入到页面中的组件也使用了带有自己缓存配置的 use cache 指令，则会比较外部和内部缓存配置，并应用配置文件中设置的最短持续时间。

app/components/parent.tsx
// Parent component
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'
 
export async function ParentComponent() {
  'use cache'
  cacheLife('days')
 
  return (
    <div>
      <ChildComponent />
    </div>
  )
}

在另一个文件中，我们定义了导入的 Child 组件

app/components/child.tsx
// Child component
import { unstable_cacheLife as cacheLife } from 'next/cache'
 
export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>
 
  // This component's cache will respect the shorter 'hours' profile
}

相关内容

查看相关的 API 参考。

dynamicIO

了解如何在 Next.js 中启用 dynamicIO 标志。

use cache

了解如何在你的 Next.js 应用程序中使用 use cache 指令来缓存数据。

revalidateTag

revalidateTag 函数的 API 参考。

cacheTag

了解如何在你的 Next.js 应用程序中使用 cacheTag 函数来管理缓存失效。