cacheLife

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

使用方法

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

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
  },
}

export default nextConfig

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

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('hours')
  return <div>Page</div>
}

参考

默认缓存配置

Next.js 提供了一组基于不同时间尺度的命名缓存配置。如果在使用 use cache 指令时未在 cacheLife 函数中指定缓存配置，Next.js 会自动应用 default 缓存配置。

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

用于引用缓存配置的字符串值本身没有内在含义，它们仅作为语义标签使用。这有助于您在代码库中更好地理解和管理缓存内容。

须知：更新 staleTimes 和 expireTime 配置选项也会更新 default 缓存配置的 stale 和 expire 属性。

自定义缓存配置

您可以通过在 next.config.ts 文件的 cacheLife 选项中添加配置来定义自定义缓存配置。

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

stale 属性与 staleTimes 设置的不同之处在于它专门控制客户端路由缓存。staleTimes 是影响所有动态和静态数据实例的全局设置，而 cacheLife 配置允许您在每个函数或路由的基础上定义 stale 时间。

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

示例

定义可重用的缓存配置

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

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      biweekly: {
        stale: 60 * 60 * 24 * 14, // 14 天
        revalidate: 60 * 60 * 24, // 1 天
        expire: 60 * 60 * 24 * 14, // 14 天
      },
    },
  },
}

module.exports = nextConfig

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

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife('biweekly')
  return <div>Page</div>
}

覆盖默认缓存配置

虽然默认缓存配置提供了一种有用的方式来思考任何可缓存输出的新鲜度或过期程度，但您可能更喜欢不同的命名配置以更好地与应用程序的缓存策略对齐。

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

以下示例展示如何覆盖默认的 "days" 缓存配置：

const nextConfig = {
  experimental: {
    dynamicIO: true,
    cacheLife: {
      days: {
        stale: 3600, // 1 小时
        revalidate: 900, // 15 分钟
        expire: 86400, // 1 天
      },
    },
  },
}

module.exports = nextConfig

内联定义缓存配置

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

'use cache'
import { unstable_cacheLife as cacheLife } from 'next/cache'

export default async function Page() {
  cacheLife({
    stale: 3600, // 1 小时
    revalidate: 900, // 15 分钟
    expire: 86400, // 1 天
  })

  return <div>Page</div>
}

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

use cache 和 cacheLife 的嵌套使用

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

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

// 父组件
import { unstable_cacheLife as cacheLife } from 'next/cache'
import { ChildComponent } from './child'

export async function ParentComponent() {
  'use cache'
  cacheLife('days')

  return (
    <div>
      <ChildComponent />
    </div>
  )
}

在单独的文件中，我们定义了导入的子组件：

// 子组件
import { unstable_cacheLife as cacheLife } from 'next/cache'

export async function ChildComponent() {
  'use cache'
  cacheLife('hours')
  return <div>Child Content</div>

  // 此组件的缓存将遵循较短的 'hours' 配置
}