跳到主要内容

cacheLife

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描述
default5 分钟15 分钟1 年默认配置文件，适用于不需要频繁更新的内容
seconds01 秒1 秒适用于需要近实时更新的快速变化内容
minutes5 分钟1 分钟1 小时适用于在一小时内频繁更新的内容
hours5 分钟1 小时1 天适用于每日更新但可以稍微过时的内容
days5 分钟1 天1 周适用于每周更新但可以过时一天的内容
weeks5 分钟1 周30 天适用于每月更新但可以过时一周的内容
max5 分钟30 天1 年适用于很少需要更新的非常稳定的内容

用于引用缓存配置文件的字符串值本身没有固有含义；相反，它们作为语义标签。这允许你在代码库中更好地理解和管理缓存内容。

提示：更新 staleTimes 和 expireTime 配置选项也会更新 default 缓存配置文件的 stale 和 expire 属性。

自定义缓存配置文件​

你可以通过在 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 天
        revalidate: 60 * 60 * 24, // 1 天
        expire: 60 * 60 * 24 * 14, // 14 天
      },
    },
  },
}

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 小时
        revalidate: 900, // 15 分钟
        expire: 86400, // 1 天
      },
    },
  },
}

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 小时
    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 指令和自己的缓存配置文件，则比较外部和内部缓存配置文件，并应用配置文件中设置的最短持续时间。

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

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

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

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

app/components/child.tsx
// 子组件
import { unstable_cacheLife as cacheLife } from 'next/cache'

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

  // 此组件的缓存将尊重较短的 'hours' 配置文件
}
最后于 更新