Конфигурация сегментов маршрутов

Параметры, описанные на этой странице, отключаются при включении флага dynamicIO и в будущем будут устаревшими.

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

Параметры

experimental_ppr

Включает частичный предварительный рендеринг (PPR) для макета или страницы.

export const experimental_ppr = true
// true | false

export const experimental_ppr = true
// true | false

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': Принудительно включает динамический рендеринг, что приводит к рендерингу маршрутов для каждого пользователя во время запроса. Эквивалентно:
  • Установке параметра { cache: 'no-store', next: { revalidate: 0 } } для каждого запроса fetch() в макете или странице.
  • Установке конфигурации сегмента export const fetchCache = 'force-no-store'.
• 'error': Принудительно включает статический рендеринг и кэширование данных макета или страницы, вызывая ошибку при использовании динамических API или некэшированных данных. Эквивалентно:
  • getStaticProps() в директории pages.
  • Установке параметра { cache: 'force-cache' } для каждого запроса fetch() в макете или странице.
  • Установке конфигурации сегмента fetchCache = 'only-cache', dynamicParams = false.
  • dynamic = 'error' изменяет значение по умолчанию для dynamicParams с true на false. Можно вернуть динамический рендеринг страниц для параметров, не сгенерированных generateStaticParams, вручную установив dynamicParams = true.
• 'force-static': Принудительно включает статический рендеринг и кэширование данных макета или страницы, заставляя cookies, headers() и useSearchParams() возвращать пустые значения. Возможно использование revalidate, revalidatePath или revalidateTag на страницах или макетах, отрендеренных с force-static.

Важно знать:

• Инструкции по миграции с 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.
• Для статического рендеринга всех путей при первом посещении необходимо вернуть пустой массив в generateStaticParams или использовать export const dynamic = 'force-static'.
• При dynamicParams = true сегмент использует потоковый рендеринг на стороне сервера (Streaming Server Rendering).

revalidate

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

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

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

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

Важно знать:

• Значение revalidate должно быть статически анализируемым. Например, revalidate = 600 допустимо, а revalidate = 60 * 10 — нет.
• Значение 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

Рекомендуется использовать среду выполнения Node.js для рендеринга приложения и среду выполнения Edge для промежуточного ПО (Middleware).

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

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

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

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 для установки ограничений.

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

export const maxDuration = 5

export const maxDuration = 5

Важно знать:

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

generateStaticParams

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

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

История версий