Полное руководство по развертыванию Astro на VPS (Static + SSR)

Большинство фреймворков загружают пользователям целый мегабайт JavaScript и гордо называют это веб-приложением. Astro работает иначе: по умолчанию он вообще не использует JS на клиенте. Он собирает ваши компоненты, рендерит их на этапе сборки и отправляет в браузер чистый HTML — до тех пор, пока вы сами явно не добавите интерактивность. В этом и заключается его главная фишка, которая кардинально отличает Astro от подходов React или Next.

В этом руководстве мы разберем оба варианта деплоя: статический (когда Nginx раздает готовые HTML-файлы) и SSR (с использованием адаптера Node.js, менеджера процессов PM2 и Nginx в качестве обратного прокси). Выбирайте тот, который больше подходит для вашего проекта.

Что умеет Astro

Astro — это веб-фреймворк с упором на контент, в котором использование JavaScript опционально. Страницы создаются в формате .astro — это смесь блока со скриптами (frontmatter) и шаблонизатора, похожего на HTML. Вы можете добавлять компоненты React, Vue, Svelte, Solid или Preact прямо к родным компонентам .astro, а фреймворк сам все правильно соберет.

Итоговый результат зависит от того, какой режим вы настроите:

• Статический режим (output: 'static') на этапе компиляции превращает каждую страницу в простые .html файлы. Nginx отдает их напрямую — без запуска Node.js и каких-либо дополнительных затрат вычислительных ресурсов. Подойдет для блогов, документации, промо-сайтов и любых проектов, где контент не меняется при каждом запросе.
• Серверный режим (output: 'server') запускает сервер Node.js, который генерирует страницы на лету. Этот режим нужен для динамических маршрутов, обработки форм, сессий авторизации, персонализированного контента или API-эндпоинтов, которые зависят от данных конкретного запроса.

Важно знать: для Astro 6.x требуется Node.js версии 22.12.0 или выше. Если на вашем сервере установлена более старая версия, первым делом обновите Node — без этого сборка не запустится.

Для чего Astro подходит хуже. Astro — это не замена полноценному бэкенду. Да, API-маршруты здесь работают, но если вы планируете создавать тяжелый REST API или сервер на WebSocket для работы в реальном времени, вы будете лишь бороться с фреймворком, а не писать код. Однако для контентных сайтов и легкого SSR — это превосходный инструмент.

Static против SSR: когда имеет смысл использовать свой сервер

Размещение проекта на собственном сервере дает вам то, чего лишены популярные облачные платформы: полный контроль над тем, где именно физически работает ваш сайт. Это особенно важно, если ваши пользователи находятся в определенном регионе, вам нужно соблюдать местные законы о хранении данных или вы просто не хотите, чтобы весь ваш трафик по умолчанию проходил через американские CDN-сети.

У is*hosting есть VPS-серверы в более чем 40 странах, поэтому вы можете разместить проект как можно ближе к своей аудитории или в подходящей юрисдикции. Платформы вроде Vercel, конечно, удобны, но там они диктуют правила деплоя. На своем VPS хозяин — только вы.

Что понадобится перед началом настройки

Минимальные требования:

• VPS-сервер с установленной операционной системой Ubuntu 22 или 24.
• SSH-доступ с правами root или sudo.
• Node.js версии 22.12.0 или выше (установим в процессе).
• Nginx.
• Доменное имя (опционально, но потребуется для настройки HTTPS).
• Только для SSR: менеджер процессов PM2.

О выборе тарифа:

• Для статического сайта: вполне достаточно тарифа Lite (1 vCPU / 1 ГБ оперативной памяти, от $5.94 в месяц). Nginx, раздающий готовые HTML-файлы, практически не расходует ресурсы.
• Для SSR: лучше выбрать тариф Start (2 vCPU / 2 ГБ оперативной памяти / 30 ГБ NVMe, от $10.19 в месяц при годовой оплате). В режиме ожидания процесс Node.js занимает около 80–150 МБ. Если взять сервер всего с 1 ГБ памяти, останется слишком мало пространства для сборок через npm, так как во время компиляции потребление памяти может подскакивать до 300–400 МБ.

Примечание: Node.js не установлен на VPS-тарифах от is*hosting по умолчанию, но на всех планах предоставляется корневой SSH-доступ (root). Сама установка займет около трех минут — мы подробно разберем этот процесс на Шаге 2.

Как развернуть Astro на VPS

Шаг 1: Подключение и обновление системы

Если у вас Mac или Linux, используйте терминал:

ssh root@YOUR_VPS_IP

На Windows используйте PowerShell или эмулятор терминала вроде Tabby. При первом подключении на вопрос о проверке отпечатка ключа напишите yes, затем вставьте свой пароль. Вы успешно вошли, если в консоли появилась строка вида root@hostname:~#.

Первым делом обновите список пакетов и саму систему:

apt update && apt upgrade -y

Шаг 2: Установка Node.js 22

Для Astro 6 требуется Node.js версии не ниже 22.12.0. В стандартных репозиториях Ubuntu обычно лежат более старые версии, поэтому мы воспользуемся официальным скриптом от NodeSource:

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

Проверьте, что Node.js и npm установились корректно:

node -v   # должно показать v22.x.x
npm -v

Если команда node -v выдает версию ниже 22.12, значит, скрипт NodeSource отработал с ошибкой. Прежде чем продолжать, запустите его еще раз от имени пользователя root.

Шаг 3: Установка Nginx

apt install -y nginx
systemctl enable nginx
systemctl start nginx

Убедитесь, что веб-сервер работает:

curl http://localhost

В ответ вы должны увидеть HTML-код стандартной приветственной страницы Nginx. Это значит, что можно двигаться дальше.

Шаг 4: Настройка фаервола

apt install -y ufw
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

По умолчанию сервер Node.js для Astro запускается на адресе 127.0.0.1:4321 — это локальная петля (loopback), недоступная из интернета. Публичный доступ нужен только Nginx (порты 80 и 443). Убедитесь, что правила заданы верно:

ufw status

Ожидаемый результат:

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere

Шаг 5: Перенос проекта Astro на сервер

Если ваш проект находится в Git-репозитории:

git clone https://github.com/your-username/your-astro-project.git
cd your-astro-project
npm install

Если вы просто копируете файлы со своего компьютера, воспользуйтесь утилитой scp или rsync:

rsync -avz ./your-astro-project root@YOUR_VPS_IP:/var/www/your-astro-project

Затем зайдите на сервер, перейдите в папку с проектом и установите зависимости:

cd /var/www/your-astro-project
npm install

Шаг 6: Настройка Astro под выбранный режим деплоя

Откройте файл astro.config.mjs в консольном текстовом редакторе, например в nano или vim.

Для статического режима (он работает по умолчанию — если вы не меняли этот файл, то ничего делать не нужно):

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

export default defineConfig({
  output: 'static',
});

Для режима SSR с использованием адаптера Node.js сначала нужно этот адаптер добавить:

npx astro add node

Эта команда установит пакет @astrojs/node и автоматически обновит ваш конфигурационный файл. В итоге он примет следующий вид:

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

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

Режим standalone — это именно то, что нужно для размещения проекта на VPS. Он создает самодостаточный сервер в файле dist/server/entry.mjs, который запускается одной простой командой node. Вам не потребуется оборачивать его в Express или писать дополнительный связующий код. Во время работы адаптер сам считывает переменные окружения PORT и HOST, поэтому вы можете менять адрес для подключения на лету, не пересобирая весь проект.

Шаг 7: Сборка проекта

npm run build

Первая сборка займет от 30 до 90 секунд, в зависимости от объема вашего проекта. Что получится на выходе:

• В статическом режиме: папка dist/ будет наполнена готовыми .html, .css и .js файлами. Nginx будет отдавать их посетителям напрямую.
• В режиме SSR: папка dist/client/ будет хранить статические ресурсы (ассеты), а файл dist/server/entry.mjs станет главной точкой входа для запуска сервера.

Совет: если при сборке вылетела ошибка Cannot find module, вероятнее всего, у вас несовпадение версий Node.js. Выполните команду node -v и сверьте результат с требованиями в поле engines внутри вашего файла package.json.

Раздача статического сайта Astro через Nginx

Шаг 8a: Настройка Nginx для статики

Создайте новый конфигурационный файл Nginx:

nano /etc/nginx/sites-available/astro

Вставьте в него следующий код:

server {
    listen 80;
    server_name your.domain.com;

    root /var/www/your-astro-project/dist;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html =404;
    }

    # Отдавать предварительно сжатые файлы, если они есть
    gzip_static on;
}

Активируйте конфигурацию и перезапустите сервер:

ln -s /etc/nginx/sites-available/astro /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

На заметку: команда nginx -t проверяет синтаксис конфига перед перезагрузкой. Если она выдает ошибку (test failed), внимательно прочитайте строку с ошибкой — обычно там прямо указано, в чем проблема.

Теперь откройте IP-адрес вашего VPS в браузере. Вы должны увидеть свой сайт.

Запуск SSR-сайта Astro с помощью PM2 и Nginx

Шаг 8b: Установка PM2

PM2 — это менеджер процессов для Node.js. Он следит за тем, чтобы ваше приложение продолжало работать даже после сбоев, и автоматически перезапускает его при перезагрузке сервера.

npm install -g pm2

Шаг 9: Запуск сервера Astro через PM2

cd /var/www/your-astro-project
HOST=127.0.0.1 PORT=4321 pm2 start dist/server/entry.mjs --name "astro-app"

Параметр HOST=127.0.0.1 привязывает Node-сервер только к локальному адресу — он будет недоступен напрямую из интернета, а только через Nginx. PORT=4321 — это порт Astro по умолчанию; поменяйте его, если он уже занят другим приложением.

Проверьте, что все запустилось:

pm2 status

Вы должны увидеть процесс astro-app со статусом online. Теперь проверьте последние логи:

pm2 logs astro-app --lines 20

Найдите строку Server listening on http://127.0.0.1:4321. Если она есть — все работает как нужно.

Шаг 10: Настройка автозапуска PM2 при загрузке системы

pm2 startup

В ответ PM2 выведет в консоль команду, которая начинается с sudo env PATH=.... Скопируйте ее целиком и выполните. После этого сохраните текущий список процессов:

pm2 save

Теперь после перезагрузки сервера PM2 автоматически восстановит и запустит astro-app.

Шаг 11: Настройка Nginx в качестве обратного прокси

Создайте конфигурационный файл:

nano /etc/nginx/sites-available/astro

Вставьте этот код:

server {
    listen 80;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Активируйте конфигурацию:

ln -s /etc/nginx/sites-available/astro /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Настройка HTTPS с помощью Certbot

Этот шаг актуален и для статического, и для SSR-деплоя. Прежде чем запускать команды, убедитесь, что ваш домен уже привязан к IP-адресу вашего VPS.

apt install -y certbot python3-certbot-nginx
certbot --nginx -d your.domain.com

Certbot сам внесет нужные изменения в конфигурацию Nginx и настроит автоматическое продление сертификатов через системный таймер. Проверьте, что механизм продления работает корректно:

certbot renew --dry-run

Обновление проекта на Astro

Чтобы выкатить новую версию сайта, нужно подтянуть свежий код, пересобрать проект и перезагрузить сервер.

Для статического режима:

cd /var/www/your-astro-project
git pull
npm install
npm run build
systemctl reload nginx

Для режима SSR:

cd /var/www/your-astro-project
git pull
npm install
npm run build
pm2 restart astro-app

Важно: перед крупными обновлениями самой версии Astro (через команду npm update astro), всегда делайте резервную копию текущей сборки:

cp -r dist dist.bak

И хотя is*hosting предоставляет бесплатные еженедельные бэкапы на всех тарифах (это снимки всего сервера целиком), восстановить конкретную папку dist/ вручную будет гораздо быстрее, если новый деплой вдруг что-то сломает.

Три вещи, которые нужно знать перед запуском в продакшен

Адаптер Node.js умеет раздавать и статику, и SSR-маршруты. В режиме standalone файл dist/server/entry.mjs автоматически отдает файлы из папки dist/client/. Вам не нужно писать отдельный блок конфигурации в Nginx для статических файлов при работе с SSR — сервер Node сам с этим справится. Тот конфиг Nginx, который мы делали выше, просто проксирует абсолютно все запросы на Node.

Переменные окружения ведут себя по-разному при сборке и во время работы. Секретные ключи из файла .env, используемые при сборке, «вшиваются» в итоговый код. Поэтому для секретов, нужных именно во время работы сервера (например, пароли от баз данных или API-ключи), передавайте их напрямую при запуске:

DATABASE_URL=postgres://... PORT=4321 pm2 start dist/server/entry.mjs --name "astro-app"

Либо пропишите их в конфигурационном файле PM2, чтобы все выглядело аккуратнее:

nano ecosystem.config.cjs

module.exports = {
  apps: [{
    name: 'astro-app',
    script: './dist/server/entry.mjs',
    env: {
      HOST: '127.0.0.1',
      PORT: 4321,
      DATABASE_URL: 'postgres://...',
    },
  }],
};

Затем просто запустите: pm2 start ecosystem.config.cjs

Гибридный режим позволяет миксовать Static и SSR для разных страниц. Установите output: 'server' в настройках глобально, а затем добавляйте строку export const prerender = true в те конкретные страницы, которые нужно собрать заранее при деплое. Эти страницы будут отдаваться как статика, а все остальные — генерироваться по запросу. Это очень удобно, когда бо́льшая часть сайта статична, но паре маршрутов нужна серверная логика.

Альтернатива: автоматизация деплоя через Coolify. Если вам не хочется возиться с Nginx, PM2 и SSL-сертификатами вручную, is*hosting предлагает готовый образ с предустановленным Coolify прямо в конфигураторе VPS. Coolify — это PaaS-решение с открытым исходным кодом, которое берет на себя автоматический деплой из Git, настройку SSL и управление приложениями в один клик через удобную панель. Подключите свой репозиторий, укажите проект Astro, и Coolify сделает все остальное — включая автоматические пересборки при каждом пуше. Подробно этот процесс описан в руководстве is*hosting по селф-хостингу с помощью Coolify.

Решение частых проблем

• Сборка падает с ошибкой «Cannot find module» или жалуется на версию Node. Выполните команду node -v. Если версия ниже 22.12.0, переустановите Node.js с помощью скрипта NodeSource, как описано в Шаге 2.
• У процесса в PM2 статус errored. Посмотрите последние логи командой pm2 logs astro-app --lines 50. Самая частая причина — забытая переменная окружения или конфликт портов. Убедитесь, что нужный порт свободен: ss -tlnp | grep 4321.
• Nginx выдает ошибку 502 Bad Gateway. Это означает, что сервер Node.js не запущен или не прослушивает ожидаемый порт. Выполните pm2 status и проверьте логи. Если приложение выключено, перезапустите его: pm2 restart astro-app.
• Статический сайт выдает ошибку 404 при прямом переходе по ссылке. За корректную обработку таких ссылок отвечает строка try_files $uri $uri/ $uri.html =404; в конфигурации Nginx. Если ее нет в вашем конфиге, Nginx просто не догадается искать файл about.html, когда пользователь перейдет по адресу /about.

Что мы получили в итоге

Деплой Astro занимает менее 20 минут на любом Linux VPS. Статической сборке нужен только Nginx, и ресурсов она потребляет самый минимум. Режим SSR добавляет в эту связку Node.js и PM2, но все равно остается очень легким — грамотно настроенный сервер на тарифе Start справится с нагрузкой без малейших усилий.

Если вы в поиске сервера, тарифы на VPS от is*hosting начинаются от $5.94/мес для статических сайтов и от $10.19/мес для проектов с SSR. А если в будущем вы захотите прикрутить к своему Astro-сайту какую-нибудь автоматизацию, у is*hosting есть готовый к развертыванию образ с n8n, который составит вашему проекту отличную пару.