Динамические маршруты в Next.js

TL;DR

Динамические маршруты позволяют генерировать страницы на основе параметров URL, например slug для постов блога. Для статической генерации используйте вместе getStaticPaths и getStaticProps; если данные меняются часто — getServerSideProps. В статье — примеры кода, советы по вложенным маршрутам и контрольный список для разработчика.

Черно‑белая фотография дороги сверху

Динамические маршруты — это страницы, которые в URL принимают параметры. Они особенно полезны для контента, который повторяется по структуре, но отличается данными: статьи, товары, профили пользователей и т. п. Вместо создания отдельного компонента для каждой страницы вы создаёте шаблон и подставляете данные по параметру.

Ниже — практическое руководство по созданию динамического маршрута в Next.js, с примерами getStaticProps, getStaticPaths, getServerSideProps, вложенными маршрутами и рекомендациями по выбору подхода.

Что такое динамический маршрут (простыми словами)

Динамический маршрут — это файл страницы с именем в квадратных скобках, например [slug].js. Браузер видит конкретный URL (например /dynamic-routes-nextjs), а Next.js подставляет значение параметра в компонент.

Определение в одну строку: динамический маршрут позволяет одному файлу страницы обслуживать набор URL, отличающихся параметром.

Основы: как создать динамический маршрут

В папке pages создайте файл с именем в квадратных скобках: [slug].js, [id].js и т. п.
Внутри экспортируйте компонент страницы и — в зависимости от подхода — getStaticProps/getStaticPaths или getServerSideProps.

Пример краткого компонента Post:

const Post = ({ postData }) => {
  return {/* content */};
};

export default Post;

getStaticProps — когда брать данные на этапе сборки

Если контент меняется редко (статические статьи, документация, продукты с редкими обновлениями), предпочтительна статическая генерация:

Производительность: страницы собираются и раздаются как статические файлы.
SEO: содержимое видно сразу поисковым ботам.
Ограничение: данные обновляются только при пересборке (или при ISR — Incremental Static Regeneration).

Пример использования getStaticProps для поста:

import { getSinglePost } from "../../utils/posts";

const Post = ({ content }) => {
  return {/* content */};
};

export const getStaticProps = async ({ params }) => {
  const post = await getSinglePost(params.slug);

  return {
    props: { ...post },
  };
};

export default Post;

getStaticProps получает params, которые передаёт getStaticPaths (ниже). Именно getStaticProps отвечает за формирование пропсов страницы во время сборки.

getStaticPaths — как сгенерировать список маршрутов

getStaticPaths возвращает массив путей (paths), которые нужно предварительно отрендерить. Обычно вы достаёте все доступные записи и мапите их в объект { params: { slug } }.

Пример:

export const getStaticPaths = async () => {
  const paths = getAllPosts().map(({ slug }) => ({ params: { slug } }));

  return {
    paths,
    fallback: false,
  };
};

Параметр fallback управляет поведением для путей, которых нет в paths:

false — любые отсутствующие пути приводят к 404.
true или ‘blocking’ — страницы могут генерироваться на запрос.

Полный пример [slug].js

import { getAllPosts, getSinglePost } from "../../utils/posts";

const Post = ({ content }) => {
  return {content};
};

export const getStaticPaths = async () => {
  const paths = getAllPosts().map(({ slug }) => ({ params: { slug } }));

  return {
    paths,
    fallback: false,
  };
};

export const getStaticProps = async ({ params }) => {
  const post = await getSinglePost(params.slug);

  return {
    props: { ...post },
  };
};

export default Post;

Важно: для статической генерации getStaticPaths и getStaticProps обычно используются вместе — первый задаёт набор URL, второй наполняет страницы данными.

Вложенные динамические маршруты

Чтобы создать URL типа /posts/dynamic-routes-nextjs, положите [slug].js в папку pages/posts:

pages/posts/[slug].js

Так же можно создавать многоуровневые шаблоны: pages/users/[id]/settings.js и т. д.

Получение параметров из URL на клиенте

Если нужно прочитать параметры внутри компонента на клиентской стороне, используйте хук useRouter:

import { useRouter } from 'next/router'

const Post = () => {
  const router = useRouter()
  const { slug } = router.query
  return Post: {slug}
}

export default Post

Этот способ полезен для клиентских эффектов или когда вы не используете getStaticProps/getServerSideProps.

getServerSideProps — когда рендерить на каждый запрос

Если данные меняются очень часто (реальное состояние, кастомная персонализация, чувствительная к времени информация), используйте getServerSideProps. Каждый запрос вызывает серверную функцию и возвращает props.

Плюсы: всегда актуальные данные. Минусы: медленнее, требует серверных ресурсов и снижает кэшируемость.

Сравнение: getStaticProps vs getServerSideProps

Подход	Когда подходит	Минусы

|getStaticProps + getStaticPaths| Статические страницы, блоги, документация, продукты с редкими изменениями | Обновления появляются после пересборки (если не использовать ISR) |getServerSideProps| Часто меняющиеся данные, персонализация, страницы с авторизацией | Медленнее, нагрузка на сервер

Когда статические маршруты не подойдут (контрпримеры)

Вы хотите отображать реальные данные, которые меняются каждую секунду (например, цены на бирже). В этом случае static не подойдёт.
Персонализированный контент, зависящий от сессии или куки, лучше отдавать серверно.
Огромный список динамических путей (миллионы) — предварительная генерация всех путей неэффективна; используйте fallback и/или пагинацию.

Альтернативные подходы

Incremental Static Regeneration (ISR): комбинирует преимущества статической генерации и возможности обновления по расписанию.
Клиентский рендеринг (CSR): загружать данные на клиенте после первого рендера — полезно для менее важного SEO-контента.
Hybrid: статически генерировать общий шаблон, а специфические части подгружать по API.

Мини‑методология: пошагово для блога

Выберите ключевые slugs для генерации (getAllPosts).
Реализуйте getStaticPaths, возвращающий paths.
Реализуйте getStaticProps для каждого slug.
Тестируйте локально командой next build && next start.
При необходимости добавьте ISR или перейдите на getServerSideProps.

Контрольный список для разработчика

Файл страницы: pages/[slug].js или pages/posts/[slug].js
getStaticPaths возвращает корректные paths
getStaticProps получает params и возвращает props
fallback настроен согласно требованиям (false / true / ‘blocking’)
Проверить работу useRouter для клиентских эффектов
Тесты: render, 404 для неизвестных slug (если fallback: false)

Факты и подсказки

Если количество URL велико (десятки тысяч+), подумайте о стратегии пагинации или on-demand генерации (ISR или fallback).
Для SEO-важного контента статическая генерация обычно даёт лучший результат.
Если нужна персонализация по пользователю, используйте серверный рендеринг или клиентскую подгрузку с авторизацией.

Готовые шаблоны и сниппеты

Основные сниппеты уже показаны выше. Для быстрого старта возьмите полный пример [slug].js и замените getAllPosts/getSinglePost на свои функции доступа к данным.

Критерии приёмки

Страницы по known-slugs успешно рендерятся (200).
Для неизвестных slug с fallback: false — страница 404.
Данные, отображаемые на странице, соответствуют записи из хранилища.
При использовании getServerSideProps проверена производительность под ожидаемой нагрузкой.

Безопасность и конфиденциальность

Не встраивайте секреты (ключи API) в getStaticProps — это код, выполняемый на сервере во время сборки, но секреты лучше держать в переменных окружения и не попадать в клиентские пропсы.
Для персональных данных соблюдайте требования хранения и передачи данных (шифрование, передача по HTTPS).

Короткая сводка

Динамические маршруты в Next.js дают гибкость и масштабируемость: один шаблон — множество URL. Для статического контента используйте getStaticPaths + getStaticProps, для часто меняющегося — getServerSideProps. Выбирайте стратегию в зависимости от требований к свежести данных, производительности и SEO.