JS
#astro#deploy#adapter#node#netlify#vercel#ssr

Astro: адаптеры для деплоя (Node, Netlify, Vercel)

Настройка адаптеров Astro для SSR: Node (standalone), Netlify, Vercel. Установка и конфиг в astro.config.mjs.

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

  1. Выбери целевой хостинг (Node, Netlify или Vercel) и установи соответствующий adapter: pnpm astro add node | netlify | vercel.
  2. В astro.config.mjs укажи output: "server" и adapter с нужными опциями (mode для Node, edgeMiddleware для Netlify, isr для Vercel).
  3. Собери проект (pnpm build) и задеплой согласно инструкциям платформы; для Node — запуск node dist/server/entry.mjs.

При сборке Astro-проекта в режиме output: "server" или output: "hybrid" сборщик должен знать, под какую платформу генерировать серверный код. Без указания адаптера сборка либо падает с ошибкой, либо получается статический вывод без SSR. Проблема возникает при первом деплое на Node-сервер, Netlify или Vercel: после pnpm build непонятно, какой артефакт запускать или куда заливать файлы. Симптомы: ошибка «No adapter specified», пустая или нерабочая папка dist, либо деплой на платформу не находит серверную точку входа. Ниже — установка и минимальная конфигурация адаптеров Node, Netlify и Vercel по официальной документации, плюс команды проверки после сборки.

Решение

Для режимов output: "server" и output: "hybrid" в Astro нужен adapter, который подключает сборку к целевой платформе.

Установка адаптеров:

# Node.js (standalone сервер)
pnpm astro add node

# Netlify
pnpm astro add netlify

# Vercel
pnpm astro add vercel

Node.js adapter (Deploy to your own server):

// astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone", // standalone | middleware
  }),
});

Запуск после сборки:

pnpm build
node dist/server/entry.mjs

Netlify adapter (Netlify):

// astro.config.mjs
import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify";

export default defineConfig({
  output: "server",
  adapter: netlify({
    edgeMiddleware: true, // опционально: Edge Functions для middleware
  }),
});

Деплой: подключить репозиторий, Build command — pnpm build, Publish directory — dist.

Vercel adapter (Vercel):

// astro.config.mjs
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
  output: "server",
  adapter: vercel({
    isr: {
      expiration: 60, // ISR: ревалидация каждые 60 секунд (опционально)
    },
  }),
});

Деплой: подключить репозиторий, Framework Preset — Astro, Build Command — pnpm build, Output Directory — dist.

  • После смены adapter пересобери проект: pnpm build.
  • Секреты задавай в переменных окружения платформы (Netlify/Vercel dashboard или .env локально).
  • Для Node на своём сервере можно добавить process manager (systemd, PM2) и reverse proxy (Nginx).

Проверка

  1. Локальная сборка и запуск (Node adapter):
pnpm build
node dist/server/entry.mjs

Ожидаемый вывод: сервер слушает порт (часто 4321 или из переменной окружения). Открой в браузере http://localhost:4321 и проверь страницы, в том числе с SSR.

  1. Проверка наличия серверной точки входа (диагностика):
ls -la dist/server/

Должен быть файл entry.mjs (или аналог для выбранного adapter). Если папки server нет или она пустая — проверь output: "server" в конфиге и что установлен нужный adapter.

  1. Netlify/Vercel: после деплоя открой URL сайта и убедись, что маршруты с prerender: false отдают контент (не 404). В логах сборки на платформе не должно быть ошибок «No adapter» или «Missing server entry».

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

  • Ошибка «No adapter specified» или сборка не создаёт серверный код — в astro.config.mjs указан output: "server" или "hybrid", но не задан adapter. Установи и подключи один из адаптеров (node, netlify, vercel).
  • На Netlify/Vercel деплой есть, но SSR-страницы отдают 404 — проверь, что Publish/Output directory указан как dist и платформа использует serverless/edge функции (обычно подхватывается автоматически после astro add).
  • Для статического сайта (output: "static") адаптер не нужен — не подключай adapter, если весь сайт статический; иначе сборка может ожидать серверную среду.

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

  • Prod: деплой на свой сервер (Node adapter + PM2/systemd + Nginx), Netlify или Vercel.
  • Dev: локально pnpm dev работает без adapter; для проверки production-сборки используй pnpm build и node dist/server/entry.mjs (Node).
  • Docker: образ на Node.js, запуск entry.mjs; переменные окружения передавать через -e или env-файл.

Связанные сниппеты: API Route (endpoint), Форма с валидацией Zod (Actions), Статический вывод по умолчанию.

⚠️ Режим output: "server" или "hybrid" требует выбранный adapter; без него сборка с SSR не заработает. Для статического сайта (output: "static") адаптер не нужен — можно деплоить dist на любой статический хостинг.

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