Статика, динамика и всё между ними

В части II перерисовка запускалась от действия: клик — новое состояние — новая разметка, и вопрос был один — когда перерисовать. У серверного компонента этого вопроса нет: он выполняется один раз за свою жизнь. Весь вопрос в том, когда эта жизнь наступает. Кандидатов ровно два: минута, когда идёт next build, и момент, когда в сервер стучится настоящий HTTP-запрос. Выбирает Next сам, и по умолчанию берёт первый вариант.

Выбрав сборку, он вызывает ваш компонент прямо там, получает разметку и кладёт готовый файл на диск. Дальше на запросы отвечает файл — в ваш код сервер уже не заходит. Разницу удобно разглядеть на модели, где clock() играет роль всего, что может измениться между выкатом и заходом читателя.

let minute = 0;

function clock(): string {
  minute += 1;
  return "минута " + minute;
}

function Page(): string {
  return "страница собрана в " + clock();
}

// статика: компонент зовут один раз, на сборке, и запоминают строку
const prerendered = Page();
console.log(prerendered);
console.log(prerendered);

// динамика: компонент зовут заново на каждый запрос
console.log(Page());
console.log(Page());

Первые две строки совпали не потому, что часы встали, а потому что Page во второй раз просто не звали. Статическая страница — это не «быстрый рендер», это отсутствие рендера.

Убедиться можно и без модели. Соберите приложение и загляните в .next/server/app/: у статической страницы там лежит настоящий .html со всем текстом внутри, у динамической — только код, который этот текст когда-нибудь построит.

next dev собирает страницу заново на каждый запрос — даже ту, что в проде застынет навсегда. Отсюда классическое «на локалке обновлялось»: заморозку видно только после next build.

Разница заметна и снаружи, в заголовках ответа. Статическая страница приезжает с Cache-Control: s-maxage=31536000 и пометкой x-nextjs-prerender: 1; динамическая — с private, no-cache, no-store, max-age=0, must-revalidate. Это тот же самый выбор, только сформулированный для прокси и браузера.

Гадать о режиме не нужно: в конце сборки Next печатает таблицу маршрутов, а под ней — легенду значков. Для маленького приложения она выглядит так.

Колонки Revalidate и Expire заполняются только у страниц со сроком годности — про них раздел ниже. Пустая колонка у ○ означает буквально «собрано один раз и до следующего выката не изменится».

Читать этот список стоит на каждом выкате. ƒ там, где вы ждали ○, — уже найденная ошибка: кто-то в общем коде дотянулся до данных запроса, и страницы поехали считаться заново на каждый заход.

Одна невнимательная строка в app/layout.tsx делает динамическим весь сайт: корневая раскладка входит в каждый маршрут.

Список того, что превращает ○ в ƒ, невелик, и его стоит держать в голове целиком. Объединяет пункты одно: все они просят что-то, чего на сборке физически нет.

Строка про fetch ловит чаще остальных. Обычный fetch(url) статику не ломает: на сборке он один раз сходит за данными, и ответ застынет в разметке вместе со всем прочим. А дописанный cache: "no-store" — это уже заявление о свежести, и весь маршрут уезжает в ƒ.

Полезно помнить и зеркальный список — то, что динамику не включает, хотя многие ждут обратного: Math.random(), new Date(), чтение файла, запрос в базу. Всё это спокойно выполнится на сборке, а результат застынет в разметке до следующего выката.

Отдельная ловушка — похожие названия. У fetch есть значение force-cache, у сегмента — force-static, и перепутать их легко. Компилятор в этом месте помогает: допустимых значений у настройки ровно четыре.

// так Next описывает настройку сегмента: четырёх значений хватает на всё
type SegmentDynamic = "auto" | "error" | "force-static" | "force-dynamic";

const dynamic: SegmentDynamic = "force-cache";
console.log(dynamic);

Диагностика короткая и точная: Тип "force-cache" не может быть назначен для типа "SegmentDynamic". Выполнение при этом прошло и напечатало строку — типы живут только до запуска, и это ровно тот урок из части III.

В настоящем page.tsx перед строкой стоит export. Песочница выполняет один файл без модулей, поэтому в примерах это слово опущено — во всём остальном код тот же.

Откуда фреймворк знает, что маршрут динамический? Он не ищет в вашем коде слово cookies — он пробует отрисовать страницу и смотрит, чем это кончится. Запроса на сборке нет, поэтому cookies() не возвращает значение, а бросает ошибку. Рендер срывается, Next её ловит и делает вывод: заранее эту страницу не собрать.

class DynamicServerError extends Error {}

// в какой фазе сейчас идёт рендер: сборка или настоящий запрос
let phase: "prerender" | "request" = "prerender";

function cookies(): { get(name: string): string } {
  // на сборке запроса нет, читать куки неоткуда — рендер прерывается броском
  if (phase === "prerender") {
    throw new DynamicServerError(
      "Route /profile couldn't be rendered statically because it used `cookies`",
    );
  }
  return { get: () => "dark" };
}

function Header(): string {
  console.log("Header отрисован");
  return "шапка";
}

function Profile(): string {
  console.log("Profile начал рендер");
  return "тема: " + cookies().get("theme");
}

function Page(): string {
  return Header() + " | " + Profile();
}

try {
  console.log(Page());
} catch (error) {
  // так Next и узнаёт про динамику: не по разбору кода, а по пойманному броску
  console.log("сборка сдалась: " + (error as Error).message);
}

phase = "request";
console.log(Page());

Смотрите на порядок строк. Header успел отрисоваться — и его работа выброшена: сорвался рендер целиком, а не одно поддерево. Именно поэтому динамика заразна вверх: одна cookies() в глубине дерева делает динамическим весь маршрут, вместе с шапкой, подвалом и всем, что прекрасно лежало бы файлом.

В обычной сборке этот срыв молчалив: маршрут просто получает ƒ, и никто ничего не сообщает. Но молчание можно выключить.

В настоящем коде всё это выглядит буднично — обычный async-компонент из главы про серверные данные.

// cookies здесь объявлен, а не импортирован: песочница выполняет один файл.
// В настоящем page.tsx наверху стоит import { cookies } from "next/headers";
declare function cookies(): Promise<{ get(name: string): { value: string } | undefined }>;

async function ThemeBadge() {
  const jar = await cookies();
  const theme = jar.get("theme")?.value ?? "light";
  return <span>тема: {theme}</span>;
}

function Page() {
  return (
    <main>
      <h1>Профиль</h1>
      <ThemeBadge />
    </main>
  );
}

console.log(typeof Page);

Динамическим маршрут делает не сам ThemeBadge, а строчка await cookies() внутри него. Уберите её — и страница вернётся в ○, ничего больше менять не придётся.

Между «раз в выкат» и «на каждый запрос» есть середина, и она закрывает большинство настоящих случаев. Каталог товаров не обязан быть свежим до секунды — достаточно, чтобы он обновлялся раз в минуту. Это и делает revalidate: страница остаётся статической, но у файла появляется срок годности.

export const revalidate = 60 в page.tsx или в layout.tsx — и в таблице сборки у маршрута заполнится колонка Revalidate значением 1m. Значок при этом остаётся ○: страница по-прежнему собрана заранее, просто не навсегда.

Самое важное — что происходит, когда срок вышел. Запрос, заставший страницу протухшей, получает старую версию: немедленно, без ожидания. И только следом Next пересобирает страницу в фоне; свежее увидит уже следующий заход.

const REVALIDATE = 60;
let version = 1;
let cached = { html: "версия 1", builtAt: 0 };

function handle(second: number): string {
  const answer = cached.html;
  if (second - cached.builtAt >= REVALIDATE) {
    version += 1;
    cached = { html: "версия " + version, builtAt: second };
  }
  return answer;
}

console.log(handle(10));
console.log(handle(70));
console.log(handle(71));

Проверяется это одной командой. Соберите приложение с revalidate = 5, запустите next start и походите к странице curlом: первый запрос после истечения срока приезжает с заголовком x-nextjs-cache: STALE и старым содержимым, следующий — с HIT и новым.

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

Второй способ занять середину — перечислить адреса заранее. generateStaticParams из статьи «Динамические сегменты и асинхронные params» возвращает список значений сегмента, и Next собирает по странице на каждое; в таблице они получают ●. Адреса, которых в списке не было, отрисуются по требованию при первом заходе — если только вы не запретили это через dynamicParams = false, тогда будет 404.

Тонкость, о которую спотыкаются: список важен не только для тех адресов, что в нём перечислены. Пока generateStaticParams у сегмента есть, адрес вне списка отрисуется при первом заходе и ляжет в кеш — второй запрос получит его уже с x-nextjs-cache: HIT. А если функции нет вовсе, перечислять Next нечего: маршрут помечается ƒ и считается заново на каждый заход.

Одна ошибка тут повторяется у всех, и в статье про сегменты она уже попадалась: id в базе — число, а сегмент адреса всегда строка.

type Params = { id: string };

const productsFromDb = [{ id: 1 }, { id: 2 }, { id: 3 }];

function generateStaticParams(): Params[] {
  return productsFromDb;
}

console.log(generateStaticParams().length);

Компилятор разворачивает причину до самой сути: Тип "number" не может быть назначен для типа "string". Починка — String(product.id) при сборке списка, а не приведение типа.

Правило простое: не мешайте Next собирать страницу заранее. Динамика — не «более честный» режим, а счёт, который выставляется на каждом заходе: время ответа, нагрузка на базу, невозможность отдать готовый файл с ближайшего к читателю сервера.

Когда динамика действительно нужна, её стараются загнать в маленький кусок страницы, а не в маршрут целиком. В классическом режиме такой возможности нет: как вы видели, сорванный рендер обрывает весь маршрут. Именно эту дыру закрывают Cache Components и директива 'use cache' — оболочка остаётся статикой, а динамические куски приезжают потоком, и в таблице сборки появляется тот самый ◐. Об этом следующая статья.

Крайний случай другого конца шкалы — сайт, у которого динамики нет вовсе. Тогда сервер Node не нужен совсем, и приложение выкладывается набором файлов; про это статья «Статический экспорт: сайт без Node на сервере» в конце главы.