cacheLife

Функция cacheLife используется для установки времени жизни кеша функции или компонента. Она должна использоваться вместе с директивой use cache и в пределах области видимости функции или компонента.

Использование

Чтобы использовать cacheLife, включите флаг dynamicIO в вашем файле next.config.js:

import type { NextConfig } from 'next'

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

export default nextConfig

const 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>
}

'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, чтобы явно определить поведение кеширования.

Строковые значения, используемые для ссылки на профили кеширования, не несут в себе внутреннего смысла; вместо этого они служат семантическими метками. Это позволяет вам лучше понимать и управлять кешированным контентом в вашей кодовой базе.

Полезно знать: Обновление параметров конфигурации staleTimes и expireTime также обновляет свойства stale и expire профиля default.

Пользовательские профили кеширования

Вы можете настроить пользовательские профили кеширования, добавив их в опцию cacheLife вашего файла next.config.ts.

Профили кеширования — это объекты, содержащие следующие свойства:

Свойство "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

const 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>
}

'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>
}

Этот встроенный профиль кеширования будет применен только к функции или файлу, в котором он был создан. Если вы хотите повторно использовать тот же профиль во всем вашем приложении, вы можете добавить конфигурацию в свойство cacheLife вашего файла next.config.ts.

Вложенное использование 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'
}