跳到内容
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 指令时始终添加缓存配置文件，以显式定义缓存行为。

配置文件StaleRevalidateExpire描述
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 选项来配置它们。

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

属性值描述要求
stale数字客户端应缓存值而不检查服务器的持续时间。可选
revalidate数字缓存应在服务器上刷新的频率；在重新验证时可能会提供过时的值。可选
expire数字值在切换到动态获取之前可以保持过时的最大持续时间；必须长于 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 函数来管理缓存失效。