Gatsby.js на Ubuntu 22.04 — установка и запуск

Важно: все команды в инструкции выполняются под пользователем, указанным в разделе «Настройка нового пользователя» (в примере — alice). Некоторые команды требуют sudo.

Что такое Gatsby.js

Gatsby.js — это бесплатный фреймворк с открытым исходным кодом для создания быстрых статических и гибридных React‑сайтов. Он сочетает преимущества статической генерации (скорость, SEO, лёгкая отдача по CDN) с возможностью подключения headless CMS и динамических данных. Основные технологии: React, Webpack, JavaScript и CSS.

Краткое определение: Gatsby генерирует страницы заранее (build), но остаётся совместим с динамическими данными через плагины и клиентские запросы.

Основные варианты использования

Блоги и маркетинговые сайты с быстрым временем загрузки.
Документация и статические порталы с контентом из headless CMS (WordPress, Contentful, Strapi и др.).
PWA и сайты с оптимизацией Core Web Vitals.

Предварительные требования

Машина с Ubuntu 22.04 (Desktop или Server).
Доступ root или пользователь с sudo.
Подключение к интернету для загрузки пакетов и зависимостей.

Настройка нового пользователя

Рекомендуется запускать разработку и установку инструментов от непривилегированного пользователя. В примере создаём пользователя alice.

Создайте пользователя alice:

useradd -m -s /bin/bash alice

Задайте пароль:

passwd alice

Добавьте alice в группу sudo:

sudo usermod -aG sudo alice

Войдите как alice и проверьте sudo:

su - alice
sudo su

Если приглашение сменилось на «root@имя_машины», права root получены. Выйдите из режима root:

exit

Создание пользователя и проверка прав

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

Почему NVM: NVM (Node Version Manager) позволяет устанавливать и переключаться между версиями Node.js на уровне пользователя. Это безопаснее и удобнее для разработки, чем глобальная установка через apt.

Обновите индекс пакетов и установите curl:

sudo apt update
sudo apt install curl

Скачайте и выполните инсталлятор NVM (версия из примера v0.39.1):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

Во время установки инсталлятор добавит конфигурацию в ваш файл ~/.bashrc. После завершения загрузите изменения в текущую сессию:

source ~/.bashrc

Проверьте установку nvm:

nvm --version
nvm --help

Результат установки nvm

Установите Node.js v16 (рекомендуемая версия в примере):

nvm install 16

Активируйте установленную версию:

nvm use 16

Проверьте версии Node.js и npm:

node --version
npm --version

Установка и использование Node.js v16 через nvm

Примечание: nvm устанавливается на уровне пользователя и не требует sudo. Повторите установку для каждого пользователя, если нужно.

Установка Gatsby CLI

Gatsby CLI упрощает создание проекта, запуск dev‑сервера и сборку проекта.

Установите gatsby-cli глобально через npm:

npm -g install gatsby-cli

Проверьте версию:

gatsby --version

В примере установлена Gatsby CLI v4.15.

Проверка версии gatsby-cli

Отключите телеметрию (по желанию):

gatsby telemetry --disable

Создание первого сайта на Gatsby

Создайте новый сайт (интерактивный мастер):

gatsby new

Вас попросят ввести параметры проекта (название, директория, язык — JavaScript/TypeScript, CMS, система стилей и т. п.). В примере:

Название: Test Gatsby site
Директория: test-site
Язык: JavaScript
CMS: No (or I’ll add it later)
Система стилей: Theme UI

После завершения установки зависимостей появится директория test-site с исходниками.

Создание проекта через gatsby new

Перейдите в директорию проекта и запустите dev‑сервер, привязав его к IP вашей машины (пример 192.168.10.15):

cd test-site/
gatsby develop -H 192.168.10.15

Опция -H указывает bind address. По умолчанию используется порт 8000.

В конце вы увидите сообщение об успешном запуске и адрес, по которому доступен сайт:

http://192.168.10.15:8000

Запуск dev сервера Gatsby

Откройте в браузере указанный адрес для просмотра стартовой страницы Gatsby.

Стандартная стартовая страница Gatsby

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

NVM не найден после установки
- Убедитесь, что строка инициализации nvm добавлена в ~/.bashrc или ~/.profile.
- Выполните source ~/.bashrc или перезапустите терминал.
gatsby не запускается или не найден
- Проверьте, что npm глобальные пакеты находятся в PATH пользователя. Для nvm глобальные пакеты доступны только в контексте версии Node, активированной nvm.
Порт 8000 занят
- Укажите другой порт: gatsby develop -p 9000 -H 0.0.0.0
Ошибки с плагинами CMS
- Проверьте версии плагинов и их совместимость с текущей версией Gatsby; читайте документацию плагина.

Короткий чек-лист для диагностики:

Проверить node –version и npm –version
Убедиться, что gatsby –version возвращает значение
Проверить переменные окружения и PATH
Просмотреть логи сборки для подсказок об ошибках

Безопасность и харднинг при разработке

Не запускайте dev‑сервер в продакшн‑режиме. Dev‑сервер предназначен только для разработки.
Не храните секреты и ключи в репозитории. Для переменных используйте environment variables или секреты в CI/CD.
Проверяйте зависимости на уязвимости: npm audit и периодические обновления.
Ограничьте доступ к локальному dev‑серверу через firewall, если он доступен в сети.

Альтернативные способы установки Node.js

apt (официальный репозиторий Ubuntu): удобно, но версии могут отставать.
NodeSource (репозиторий): устанавливает современные версии Node глобально через apt.
Docker: запуск в изолированном контейнере с нужной версией Node, удобно для CI или унифицированной среды.

Когда NVM подходит не лучшим образом:

Если вы разворачиваете автоматизированную CI/CD сборку на сервере, удобнее использовать Docker или Node.js из репозитория/NodeSource для предсказуемости окружения.

Когда Gatsby не лучший выбор

Очень динамичные приложения с интенсивными пользователями (напрямую реализуемые на Next.js с серверным рендерингом или на чистом Node/Express).
Если вам нужна полноценная серверная логика на стороне рендера с динамическими пользовательскими состояниями при первичном запросе.

Ментальные модели и принципы использования Gatsby

Генерация страниц = build-time + плагины. Думайте, что контент собирается заранее, а динамика добавляется через клиентские запросы или incremental builds.
Источники данных: Gatsby работает как композитор — плагины подключают данные из разных CMS и источников.
Разделение статической части и клиентских интерактивных компонентов: предпочтите статический рендер для SEO и скорости, а JS оставить для интерактивности.

Фактбокс: ключевые параметры примера

OS: Ubuntu 22.04
Node.js: v16 (установлен через nvm)
Gatsby CLI: v4.15 (в примере)
Dev порт по умолчанию: 8000
Пример пользователя: alice

Чек‑лист перед деплоем

Установлена и протестирована production сборка: gatsby build
Статические файлы корректно генерируются в папке public
Отключена телеметрия и удалены dev‑only зависимости
Конфиденциальные данные вынесены в переменные окружения
Сборка интегрирована в CI/CD и тесты проходят

Ролевые чек‑листы

Разработчик:

Инициализировать проект, настроить ESLint/Prettier
Настроить nvmrc или document версию Node
Проверить работу локального сервера

DevOps:

Настроить CI для сборки и деплоя
Выбрать стратегию кеширования и CDN
Обеспечить безопасность переменных окружения

Контент‑менеджер:

Настроить подключение к выбранному CMS
Проверить корректность данных в продьюсере

Сравнение подходов развертывания

Статический хостинг (Netlify, Vercel, Cloudflare Pages): быстрый CDN, простая деплой цепочка.
Серверная сборка + CDN: если нужны incremental rebuilds или серверные функции.
Docker: полезен для унификации окружения и CI.

Короткая галерея крайних случаев

Крайний случай: нужен realtime‑функционал — Gatsby дополнит API, но реальные realtime‑функции лучше реализовать отдельным бэкендом.
Крайний случай: сложные рендеры на сервере — рассмотрите Next.js с SSR.

Малый глоссарий

NVM: менеджер версий Node.js для пользователя.
Gatsby CLI: инструмент командной строки для создания и управления Gatsby‑проектами.
Headless CMS: CMS, поставляющая контент через API без фронт‑энда.

Критерии приёмки

Сайт собирается командой командой gatsby build без ошибок.
Dev‑сервер успешно запускается и отображает стартовую страницу.
В репозитории есть README с инструкциями установки и запуска.

Короткий список альтернатив

Next.js — если нужен SSR и гибридный подход (SSR + SSG).
Hugo, Jekyll — если нужен более простой, статический генератор на Go/Ruby.
Create React App — если вам нужен SPA без статической генерации.

Подсказки для развёртывания и производительности

Используйте CDN для доставки статических файлов.
Включите Image optimization плагины и lazy loading.
Настройте кэширование и заголовки (Cache-Control) для статики.

Краткое объявление команды (100–200 слов)

Gatsby.js обеспечивает быстрый старт для создания современных сайтов и приложений на React. В этом руководстве показано пошаговое развёртывание на Ubuntu 22.04: создание пользователя, установка NVM и Node.js (v16), установка gatsby-cli и создание первого проекта. Также приведены практические советы по безопасности, устранению неполадок, альтернативы и чек‑листы перед деплоем. Если вам нужен быстрый, SEO‑дружественный сайт с гибким подключением headless CMS — Gatsby остаётся отличным выбором. Для проектов с интенсивной серверной логикой рассмотрите Next.js.

Заключение

Поздравляем — вы установили Gatsby на Ubuntu 22.04, настроили Node.js через NVM и создали первый проект. Дальше: подключите источники данных, настройте сборку в CI/CD и оптимизируйте производительность под требования вашего проекта.

Краткие рекомендации:

Используйте NVM для локальной разработки.
Тестируйте сборки в CI и деплойте на CDN.
Следите за безопасностью и не храните секреты в коде.

Установка и запуск Gatsby.js на Ubuntu 22.04