Как установить и настроить Gatsby на VPS

MAATRIX

Gatsby — генератор статических сайтов на React с одной из самых больших экосистем плагинов среди статик-генераторов: готовые модули под изображения, SEO, PWA, аналитику, интеграцию с любой headless CMS через GraphQL. Но чтобы всё это заработало на своём VPS, а не на бесплатном Netlify, нужно правильно поставить Node.js, настроить конфиг проекта и отдать собранный сайт через веб-сервер. Ниже — рабочий порядок от чистого сервера до работающего HTTPS-сайта.

Требования к серверу

Gatsby собирает React-компоненты в статичный HTML и параллельно тянет GraphQL-слой над всеми источниками данных — это заметно тяжелее по памяти, чем сборка того же Hugo. Ориентир по ресурсам:

На 1 ГБ ОЗУ сборка небольшого сайта (десяток-другой страниц) обычно проходит, но с ростом числа страниц и плагинов, обрабатывающих изображения, риск упереться в JavaScript heap out of memory растёт — конкретный порог зависит от вашего проекта, не берите чужие цифры как гарантию. Если сомневаетесь — берите VPS с 4 ГБ и docs подрастёте, память для сборки лишней не бывает.

Перед установкой обновите систему и заведите отдельного пользователя без root-прав, если ещё этого не сделали:

sudo apt update && sudo apt upgrade -y
sudo adduser gatsby
sudo usermod -aG sudo gatsby
su - gatsby

Установка Node.js и Gatsby CLI

Gatsby требует Node.js — версию проверяйте под конкретный релиз Gatsby в его документации, но на конец августа 2026 актуальная LTS-ветка — 20.x или новее. Ставим через NodeSource:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs build-essential
node -v
npm -v

build-essential нужен, потому что некоторые зависимости Gatsby (например, sharp для обработки изображений) компилируют нативные бинарники при установке.

Если планируете держать на сервере несколько проектов с разными версиями Node — удобнее поставить nvm вместо системного Node.js:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

Ставим Gatsby CLI глобально:

npm install -g gatsby-cli
gatsby --version

Создание и настройка проекта

Создаём новый проект от стартового шаблона (либо клонируем существующий репозиторий, если сайт уже разрабатывался локально):

gatsby new my-site https://github.com/gatsbyjs/gatsby-starter-minimal
cd my-site
npm install

Если проект уже существует в git — просто клонируйте его и выполните npm install в директории проекта.

Основная конфигурация живёт в gatsby-config.js в корне проекта. Минимальный рабочий конфиг с типовым набором плагинов:

module.exports = {
  siteMetadata: {
    title: `Мой сайт`,
    siteUrl: `https://example.com`,
    description: `Описание сайта для SEO`,
  },
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
    `gatsby-plugin-sitemap`,
    `gatsby-plugin-robots-txt`,
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `Мой сайт`,
        start_url: `/`,
        icon: `src/images/icon.png`,
      },
    },
  ],
};

Пара нюансов, которые часто ловят на VPS:

• siteUrl обязателен для корректной работы gatsby-plugin-sitemap и абсолютных ссылок в метатегах — без него sitemap.xml сгенерируется с относительными или пустыми путями.
• Если контент тянется из headless CMS (Contentful, Strapi, WordPress по GraphQL) — токены и ключи API храните не в gatsby-config.js, а в .env.production, и подключайте через dotenv в начале файла:

require('dotenv').config({
  path: `.env.${process.env.NODE_ENV}`,
});

Файл .env.production не коммитьте в git — добавьте в .gitignore.

Сборка и локальная проверка на сервере

Собираем production-версию:

NODE_ENV=production gatsby build

Результат окажется в директории public/ — это чистый статичный HTML, CSS и JS, готовый к отдаче любым веб-сервером. Перед тем как настраивать Nginx, стоит проверить сборку локально прямо на VPS:

gatsby serve --port 9000

Команда поднимает встроенный сервер на порту 9000 (по умолчанию) и отдаёт содержимое public/. Зайдите на http://IP-сервера:9000 (не забудьте временно открыть порт в файрволе) и убедитесь, что страницы открываются, изображения подгружаются, а в консоли браузера нет ошибок 404 на ассеты — это частый симптом неверно указанного siteUrl или pathPrefix, если сайт будет жить не в корне домена.

Если сайт будет доступен по поддиректории (например, example.com/blog/), добавьте в gatsby-config.js:

module.exports = {
  pathPrefix: `/blog`,
  // ...остальной конфиг
};

и собирайте с флагом gatsby build --prefix-paths.

Отдача через Nginx

gatsby serve подходит для быстрой проверки, но для боевой отдачи статики Nginx эффективнее — он не тратит ресурсы на Node.js-процесс и умеет кэшировать, сжимать и раздавать файлы напрямую с диска. Если вы уже настраивали Nginx как reverse proxy для других сервисов на этом VPS, принцип тот же, только здесь Nginx отдаёт файлы напрямую, без проксирования на бэкенд.

Ставим Nginx, если ещё не стоит:

sudo apt install -y nginx

Копируем собранную статику в директорию, которую будет обслуживать Nginx:

sudo mkdir -p /var/www/my-site
sudo cp -r public/* /var/www/my-site/
sudo chown -R www-data:www-data /var/www/my-site

Конфиг /etc/nginx/sites-available/my-site:

server {
    listen 80;
    server_name example.com www.example.com;
    root /var/www/my-site;
    index index.html;

    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1024;

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

    # Хэшированные ассеты Gatsby (JS/CSS с хэшем в имени) кэшируем надолго
    location ~* ^/static/.*\.(js|css)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location ~* \.(jpg|jpeg|png|webp|avif|svg|ico|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public";
    }
}

try_files с фолбэком на .html важен: Gatsby генерирует директории со своим index.html для каждой страницы (/about/index.html для /about/), и стандартный try_files $uri $uri/ без явного .html-варианта иногда не подхватывает такие пути на некоторых версиях Nginx при нестандартной структуре.

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

sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Дальше — HTTPS. Проще всего через Certbot, подробный разбор шагов — в статье про установку Let's Encrypt SSL на VPS:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

Автоматизация пересборки при обновлении контента

Если контент меняется редко и вручную — достаточно повторять git pull && gatsby build && cp -r public/* /var/www/my-site/ при каждом обновлении. Для более частых обновлений удобнее простой скрипт и systemd-таймер, а не постоянно работающий процесс.

Скрипт /home/gatsby/deploy.sh:

#!/bin/bash
set -e
cd /home/gatsby/my-site
git pull origin main
npm install
NODE_ENV=production gatsby build
rsync -a --delete public/ /var/www/my-site/

Systemd-сервис /etc/systemd/system/gatsby-deploy.service:

[Unit]
Description=Rebuild Gatsby site

[Service]
Type=oneshot
User=gatsby
ExecStart=/home/gatsby/deploy.sh

И таймер /etc/systemd/system/gatsby-deploy.timer, который будет запускать пересборку, например, каждые 30 минут:

[Unit]
Description=Run Gatsby rebuild periodically

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min

[Install]
WantedBy=timers.target

sudo chmod +x /home/gatsby/deploy.sh
sudo systemctl enable --now gatsby-deploy.timer

Если контент приходит из CMS и обновляется часто, а ждать 30 минут не вариант — пересборку по вебхуку от CMS (через gatsby-cloud-webhook или собственный обработчик на Express/systemd-сокете) стоит вынести в отдельный процесс; это решение подробно разобрано в статье про деплой Gatsby-сайта на VPS.

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

• JavaScript heap out of memory при сборке. Временное решение — увеличить лимит памяти для Node.js: NODE_OPTIONS=--max-old-space-size=4096 gatsby build. Постоянное решение — добавить VPS ОЗУ или подключить swap на время сборки (для CI/CD это нормальная практика, но постоянный swap на слабом VPS замедлит сборку из-за диска).
• Ошибка компиляции sharp при npm install — обычно из-за отсутствия build-essential или несовместимой архитектуры (ARM vs x86). Установите build-essential заранее и убедитесь, что версия Node.js соответствует требованиям текущей версии Gatsby.
• 404 на все страницы, кроме главной, при заходе напрямую по URL. Это Nginx: не хватает fallback на .html в try_files, см. конфиг выше.
• Плагины не подхватывают новый контент после gatsby develop. Кэш Gatsby в .cache/ иногда протухает после смены схемы данных или обновления плагина. Помогает gatsby clean перед пересборкой — команда чистит .cache/ и public/.

Частые вопросы