Статический экспорт: сайт без Node на сервере

В .next после обычной сборки лежат не только готовые страницы, но и код, который досчитывает остальные: серверные компоненты, действия, обработчики маршрутов. Поднять всё это может только Node — отсюда и next start на боевой машине, и контейнер с рантаймом, и память, которую он ест круглые сутки.

// next.config.ts — в настоящем файле объект типизирован как NextConfig
// и уезжает через export default; здесь оба этих места опущены
const nextConfig = {
  output: "export",
};

console.log(nextConfig.output);

После этой строки next build дописывает к сборке второй шаг — экспорт. Он проходит по всем маршрутам, рисует каждый и складывает результат в out/. Никакого server.js, никакого рантайма: в папке только то, что умеет отдать сервер, ничего не выполняющий.

Дальше папку можно положить куда угодно: на бесплатный статический хостинг, в бакет за CDN, в контейнер с Caddy или nginx рядом с другими сайтами. Учебник, который вы читаете, — больше четырёхсот статей, столько же HTML-файлов — отдаётся именно так: образ собирается из caddy:2-alpine, внутрь копируется out/, и всё.

next start в этой схеме не участвует и прямо об этом скажет: "next start" does not work with "output: export" configuration. Use "npx serve@latest out" instead.

Правило одно, и оно короткое: всё, что должно выполниться в момент запроса, не переживает экспорт. Файл уже написан — переписывать его в ответ на визит некому. Отсюда весь список потерь, и он выводится, а не заучивается.

Самая обидная потеря — действия. Форма из главы про мутации выглядит безупречно и в разработке работает: next dev поднимает настоящий сервер, там есть кому принять вызов.

// app/feedback/page.tsx — под next dev эта форма работает,
// а next build с output: "export" на ней останавливается
async function save(data: FormData) {
  "use server";
  console.log("отзыв:", data.get("text"));
}

export default function Feedback() {
  return (
    <form action={save}>
      <textarea name="text" />
      <button type="submit">Отправить</button>
    </form>
  );
}

Сборка останавливается со словами Server Actions are not supported with static export — и это лучший из возможных исходов. Хуже был бы молчаливо собранный сайт, где кнопка «Отправить» не делает ничего.

Проверять экспорт надо сборкой, а не разработкой: под next dev рядом стоит Node, и всё перечисленное в таблице отлично работает. Ошибка приходит только на next build.

Отдельная ловушка — файлы-конвенции. sitemap.ts, robots.ts и любой route.ts с обработчиком GET при экспорте обязаны объявить себя статическими явно, иначе Next считает их динамическими и выгружать отказывается: export const dynamic = "force-static"/export const revalidate not configured on route "/sitemap.xml" with "output: export". В этом учебнике строка export const dynamic = "force-static" стоит в обоих файлах ровно по этой причине.

Динамический сегмент [slug] — это переменная. Пока есть сервер, подставить в неё значение можно в момент запроса; без сервера подставлять некому, а значит, все значения нужно перечислить заранее. Этим и занимается generateStaticParams: возвращает список, а шаг экспорта рисует по файлу на каждый его элемент.

// модель шага экспорта для папки app/[slug]: список имён → список файлов
type Params = { slug: string };

function generateStaticParams(): Params[] {
  return ["closures", "jsx-not-html", "static-export"].map((slug) => ({ slug }));
}

function exportRoute(pattern: string, list: Params[]): string[] {
  return list.map((params) => pattern.replace("[slug]", params.slug) + ".html");
}

const files = exportRoute("/[slug]", generateStaticParams());
console.log(files);
console.log(files.length);

В учебнике эта функция выглядит почти так же — только список берётся из оглавления, и файлов выходит по числу статей. Новая статья появляется в chapters.ts, и следующая сборка сама заводит ей адрес: руками ничего перечислять не нужно.

// app/[slug]/page.tsx этого учебника, фрагмент.
// ARTICLE_ORDER — плоский список слагов из оглавления
import { ARTICLE_ORDER } from "@jsp/content";

export function generateStaticParams() {
  return ARTICLE_ORDER.map((slug) => ({ slug }));
}

Забыть про эту функцию не получится — сборка не даст. Три сообщения, которые стоит узнавать в лицо:

Последняя строка важнее, чем кажется. При экспорте dynamicParams всегда считается ложным: адрес, которого нет в списке, не существует вовсе — файловый сервер отдаст 404.html. Для учебника это ровно то, что нужно. Для доски объявлений, где карточки заводят пользователи, — приговор: страница появится только после следующей сборки.

// нижний уровень получает params родителя и дополняет их своими
type Category = { category: string };
type Full = { category: string; id: string };

function childParams({ category }: Category): Full[] {
  const ids = category === "kettles" ? ["1", "2"] : ["7"];
  return ids.map((id) => ({ category, id }));
}

const pairs = [{ category: "kettles" }, { category: "mugs" }].flatMap(childParams);
console.log(pairs.length);
console.log(pairs[0]);

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

// строка «обновлено» посчиталась на сборке — в файл попал результат,
// а не формула
const BUILD_TIME = new Date("2026-06-01T09:00:00Z");

function ago(moment: Date, now: Date): string {
  const minutes = Math.round((now.getTime() - moment.getTime()) / 60000);
  if (minutes < 5) return "только что";
  if (minutes < 60) return minutes + " мин. назад";
  return Math.round(minutes / 1440) + " дн. назад";
}

const html = "Обновлено: " + ago(BUILD_TIME, BUILD_TIME);
console.log(html);

// читатель открыл тот же файл три месяца спустя
const visit = new Date("2026-09-08T12:00:00Z");
console.log(html);
console.log("на самом деле:", ago(BUILD_TIME, visit));

Вторая строка вывода — та самая, что увидит читатель три месяца спустя. Файл не пересчитывается от того, что его открыли; «только что» в нём написано навсегда. Это не беда экспорта как такового — так же ведёт себя любая статическая страница, — но при output: "export" статическими становятся все страницы разом, и ловушка перестаёт быть редкой.

Лечится тем же, чем всегда: значение, которого не было на сборке, вычисляется после монтирования. Первый кадр показывает то, что лежит в файле, второй — настоящее.

// в файл вшита только дата сборки — больше страница о времени ничего не знает
const BUILD_TIME = new Date("2026-06-01T09:00:00Z");

function Updated() {
  const [ago, setAgo] = React.useState<string | null>(null);
  // печатаем наличие числа, а не само число: у каждого читателя оно своё
  console.log("рендер:", ago === null ? "null" : "число из браузерных часов");
  React.useEffect(() => {
    // часы есть только у браузера: на сборке этого числа не существовало
    const days = Math.round((Date.now() - BUILD_TIME.getTime()) / 86400000);
    setAgo(days + " дн. назад");
  }, []);
  // первый кадр — ровно то, что лежит в out/: заглушка, а не пустота
  return <p id="out">Обновлено: {ago ?? "недавно"}</p>;
}

ReactDOM.createRoot(document.getElementById("root")!).render(<Updated />);
setTimeout(
  () =>
    console.log(
      "в DOM осталась заглушка:",
      document.getElementById("out")!.textContent === "Обновлено: недавно"
    ),
  50
);

В выводе две строки «рендер», и в первой — null: это и есть содержимое out/, тот кадр, который лежит в файле. Настоящее число приезжает только со второй отрисовкой — третья строка и говорит, что заглушки в разметке уже нет. Само число пример не печатает нарочно: оно зависит от дня, когда вы читаете эту страницу. Отсюда правило вёрстки для статики: заглушка должна быть не пустотой, а осмысленным текстом. Её увидят все — и читатель с отключённым JavaScript, и поисковый робот, и любой, у кого страница ещё не ожила.

Так же переезжают в браузер и данные: список комментариев, курс валют, содержимое корзины. Это старый добрый эффект из главы про синхронизацию или use() с <Suspense> — с одной поправкой. Запрос уходит из браузера читателя, значит, чужой API должен разрешать CORS, а ключ доступа к нему уезжает в бандл и виден в исходниках страницы. Прятать в статике нечего.

Переменные NEXT_PUBLIC_* вшиваются в файлы на сборке. Поменять адрес API после выкладки, не пересобирая, невозможно — в out/ лежит уже подставленное значение.

Ссылки в разметке ведут на /closures, а в папке лежит closures.html. Пока работал next start, это соответствие держал он. Теперь его держите вы — правилами файлового сервера.

// сервер знает только про файлы; порядок попыток — тот же, что в try_files
const out = ["/index.html", "/closures.html", "/static-export.html", "/404.html"];

function serve(url: string): string {
  const base = url.endsWith("/") ? url.slice(0, -1) : url;
  const tries = [url, base + ".html", base + "/index.html"];
  return tries.find((name) => out.includes(name)) ?? "/404.html";
}

console.log(serve("/closures"));
console.log(serve("/"));
console.log(serve("/closures/"));
console.log(serve("/no-such-article"));

Три строки конфига — и сайт открывается. Без них он выглядит сломанным ровно наполовину: главная работает, любая внутренняя страница отдаёт 404. Это самая частая причина растерянности после первого экспорта, и Next тут ни при чём — просто никто не сказал серверу про .html.

От правила про .html можно избавиться вовсе — поменяв раскладку папки. Настройка trailingSlash: true заставляет экспорт писать closures/index.html вместо closures.html: такой сайт открывается почти на любом сервере без настройки, потому что index.html в папке находят все. Платой будут адреса со слэшем на конце и лишний уровень вложенности. Выбирать между двумя раскладками стоит один раз — до того, как ссылки на статьи разойдутся по сети.

Второе, что настраивается руками, — HTTP-кеш браузера, тот, что слушается заголовков (кеш service worker из части II — отдельный склад, заголовков он не читает). Раздавать всё одинаково нельзя: имена чанков содержат хеш содержимого и меняются при каждой правке, а имена страниц постоянны. У учебника это выглядит так:

Теперь честно про выбор. Экспорт — не режим «для маленьких сайтов», а размен: вы отдаёте динамику и получаете взамен три вещи, которые дорого стоят. Нечему падать в три часа ночи — файлы не умеют. Нагрузка не упирается в приложение — хоть сто тысяч читателей разом. Сервер стоит копейки, а часто и вовсе ничего.

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