Конфигурация сегментов маршрутов (Route Segment Config)

Параметры сегментов маршрутов позволяют настроить поведение Страниц, Макетов или Обработчиков маршрутов (Route Handlers) путем прямого экспорта следующих переменных:

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

Полезно знать:

• Значения параметров конфигурации должны быть статически анализируемыми. Например, revalidate = 600 допустимо, а revalidate = 60 * 10 — нет.

Параметры

dynamic

Изменяет динамическое поведение макета или страницы на полностью статическое или полностью динамическое.

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

Полезно знать: Новая модель в директории app предпочитает детализированный контроль кэширования на уровне запросов fetch вместо бинарной модели "всё или ничего" с getServerSideProps и getStaticProps на уровне страниц в директории pages. Параметр dynamic позволяет вернуться к предыдущей модели для удобства и упрощения миграции.

• 'auto' (по умолчанию): Кэширует максимально возможное количество данных, не препятствуя динамическому поведению компонентов.

• 'force-dynamic': Принудительно включает динамический рендеринг (dynamic rendering), что приводит к рендерингу маршрутов для каждого пользователя во время запроса. Эквивалентно getServerSideProps() в директории pages.

• 'error': Принудительно включает статический рендеринг и кэширование данных макета или страницы, вызывая ошибку, если какие-либо компоненты используют динамические функции (dynamic functions) или некешированные данные. Эквивалентно:

  • getStaticProps() в директории pages.
  • Установке параметра { cache: 'force-cache' } для всех запросов fetch() в макете или странице.
  • Установке конфигурации сегмента в fetchCache = 'only-cache', dynamicParams = false.
  • dynamic = 'error' изменяет значение dynamicParams по умолчанию с true на false. Можно вернуть динамический рендеринг для параметров, не сгенерированных generateStaticParams, вручную установив dynamicParams = true.

• 'force-static': Принудительно включает статический рендеринг и кэширование данных макета или страницы, заставляя cookies(), headers() и useSearchParams() возвращать пустые значения.

Полезно знать:

• Инструкции по миграции с getServerSideProps и getStaticProps на dynamic: 'force-dynamic' и dynamic: 'error' можно найти в руководстве по обновлению.

dynamicParams

Определяет поведение при посещении динамического сегмента, который не был сгенерирован с помощью generateStaticParams.

export const dynamicParams = true // true | false,

export const dynamicParams = true // true | false,

• true (по умолчанию): Динамические сегменты, не включенные в generateStaticParams, генерируются по запросу.
• false: Динамические сегменты, не включенные в generateStaticParams, возвращают ошибку 404.

Полезно знать:

• Этот параметр заменяет опцию fallback: true | false | blocking в getStaticPaths из директории pages.
• При dynamicParams = true сегмент использует Потоковый серверный рендеринг (Streaming Server Rendering).
• Если используются dynamic = 'error' или dynamic = 'force-static', значение dynamicParams по умолчанию изменяется на false.

revalidate

Устанавливает время повторной валидации по умолчанию для макета или страницы. Этот параметр не переопределяет значение revalidate, установленное отдельными запросами fetch.

export const revalidate = false
// false | 0 | number

export const revalidate = false
// false | 0 | number

• false (по умолчанию): Кэширует все запросы fetch() с параметром cache: 'force-cache' или обнаруженные до использования динамических функций (dynamic functions). Эквивалентно revalidate: Infinity, что означает бессрочное кэширование. Отдельные запросы fetch могут использовать cache: 'no-store' или revalidate: 0 для избежания кэширования и динамического рендеринга маршрута. Или установить revalidate на положительное число меньше значения по умолчанию для увеличения частоты повторной валидации.
• 0: Гарантирует динамический рендеринг (dynamic rendering) макета или страницы, даже если не обнаружены динамические функции или некешированные запросы данных. Этот параметр изменяет значение по умолчанию для запросов fetch без параметра cache на 'no-store', но оставляет запросы с 'force-cache' или положительным revalidate без изменений.
• number: (в секундах) Устанавливает частоту повторной валидации по умолчанию для макета или страницы в n секунд.

Полезно знать: Параметр revalidate доступен только при использовании Node.js Runtime. Использование revalidate с runtime = 'edge' не работает.

Частота повторной валидации

• Наименьшее значение revalidate среди всех макетов и страниц одного маршрута определяет частоту повторной валидации для всего маршрута. Это гарантирует, что дочерние страницы повторно валидируются так же часто, как их родительские макеты.
• Отдельные запросы fetch могут устанавливать значение revalidate меньше значения по умолчанию для маршрута, чтобы увеличить частоту повторной валидации всего маршрута. Это позволяет динамически выбирать более частую повторную валидацию для определенных маршрутов на основе критериев.

fetchCache

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

runtime

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

• 'nodejs' (по умолчанию)
• 'edge'

Подробнее о средах выполнения Edge и Node.js.

preferredRegion

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

Поддержка preferredRegion и доступные регионы зависят от платформы развертывания.

Полезно знать:

• Если preferredRegion не указан, он наследуется от ближайшего родительского макета.
• Корневой макет по умолчанию использует все регионы.

maxDuration

По умолчанию Next.js не ограничивает выполнение серверной логики (рендеринг страницы или обработка API). Платформы развертывания могут использовать maxDuration из сборки Next.js для установки ограничений. Например, на Vercel.

Примечание: Для этой настройки требуется Next.js 13.4.10 или выше.

export const maxDuration = 5

export const maxDuration = 5

Полезно знать:

• При использовании Server Actions установите maxDuration на уровне страницы, чтобы изменить таймаут по умолчанию для всех Server Actions на странице.

generateStaticParams

Функция generateStaticParams может использоваться в сочетании с динамическими сегментами маршрутов (dynamic route segments) для определения списка параметров сегментов, которые будут статически сгенерированы во время сборки, а не по запросу.

Подробнее см. в справочнике API.