JS
#astro#output#static#ssg#config

Astro: output static — статическая сборка по умолчанию

Режим output: 'static' (по умолчанию) — все страницы генерируются при сборке. Без adapter, подходит для блогов и лендингов.

Как использовать

  1. По умолчанию output уже static; явно можно указать в astro.config.mjs: output: 'static'.
  2. Для SSR или API routes переключитесь на output: 'server' или 'hybrid' и добавьте adapter (см. сниппет по адаптерам).
  3. При static страницы с export const prerender = false не поддерживаются — используйте hybrid или server.

В Astro по умолчанию включён режим статической сборки: при astro build все страницы рендерятся в HTML-файлы, adapter не нужен. Подходит для блогов, лендингов и документации. Проблема: если ожидать серверный рендер или API без смены режима — страницы с prerender = false не собираются, API routes не работают по запросу. Симптомы: 404 на динамических маршрутах, ошибка «No adapter specified» при попытке деплоя с SSR без настройки. Ниже — что даёт output: "static", когда его выбирать и как перейти на server/hybrid по документации Output modes.

Решение

По умолчанию Astro использует output: "static": при сборке все страницы превращаются в статический HTML. Adapter не требуется.

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static', // можно не указывать — значение по умолчанию
});

Что получается:

  • Все страницы и маршруты генерируются при build в HTML.
  • Деплой на любой статический хостинг (Netlify, Vercel, GitHub Pages, CDN).
  • API routes и серверный рендер по запросу недоступны — для них нужны output: "server" или "hybrid" и adapter.

Когда выбирать static:

  • Блог, документация, лендинг, маркетинг-сайт.
  • Весь контент известен на момент сборки.
  • Интерактив через островки; формы — через внешний сервис или отдельный backend.

При output: "static" страницы с export const prerender = false не поддерживаются — такой экспорт имеет смысл только при output: "hybrid" или "server".

Проверка

  1. Текущий режим — в astro.config.mjs не указан output или указано output: 'static'. После pnpm build в dist/ лежат только статические файлы (HTML, JS, CSS), нет серверного entry (в отличие от режима server).

  2. Нет серверных маршрутов — при static API routes в src/pages/api/ вызываются только при сборке (если вообще генерируются). Для работы API по запросу переключитесь на server/hybrid и добавьте adapter.

  3. Деплой — загрузите содержимое dist/ на статический хостинг или отдавайте через nginx как статику. Серверный процесс не нужен.

Типичные ошибки

  • Ожидание SSR при static — в static режиме нет сервера, который рендерит по запросу. Для SSR нужны output: "server" или "hybrid" и adapter.
  • prerender = false при static — в статическом режиме такой экспорт игнорируется или приводит к ошибке. Используйте prerender = false только при hybrid/server.
  • API route отдаёт 404 после деплоя — в static API не работает как endpoint по запросу. Нужен режим server/hybrid и настройка API route с prerender: false.

Где применять

  • Блоги, лендинги, документация: контент из Content Collections или MDX, островки для интерактива. Деплой — статический хостинг или CDN.
  • Переход на SSR: когда понадобятся формы на сервере, API или динамические страницы по запросу — см. адаптеры деплоя и API route.

Связанные сниппеты: Адаптеры для деплоя (Node, Netlify, Vercel), API Route (endpoint), Content Collections: фильтр и сортировка, Astro Actions: форма с Zod.

Похожие сниппеты