Menu

cacheLife

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

用法

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

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

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

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

参考

默认缓存配置文件

Next.js 提供了一组基于各种时间尺度建模的命名缓存配置文件。如果你在 cacheLife 函数中没有指定缓存配置文件，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
TypeScript
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
TypeScript
'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>
  )
}

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

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' 配置文件
}

相关

查看相关的 API 参考。

use cache

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

cacheTag

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

revalidateTag

revalidateTag 函数的 API 参考。

dynamicIO

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