Развёртывание React на Ubuntu 20.04 с Nginx

Иллюстрация логотипа React и интерфейса приложения

О чём этот материал

Этот пошаговый материал объясняет, как подготовить сервер Ubuntu 20.04, установить Node.js и Create React App, создать простое приложение, организовать автозапуск и настроить Nginx как обратный прокси или как статический веб-сервер для production-сборки. Включены советы по безопасности, проверке и устранению неполадок.

Кому это полезно

Разработчикам, которые хотят быстро развернуть фронтенд-приложение на VPS.
Системным администраторам, отвечающим за простую доставку SPA.
Тем, кто хочет понять отличия между проксированием dev-сервера и раздачей production-сборки.

Основные понятия

Node.js — среда выполнения JavaScript на сервере.
Create React App — инструмент генерации шаблона React-проекта.
Nginx — веб-сервер, часто используемый как обратный прокси.

Важно: всегда обслуживайте production-сборку (npm run build) как статические файлы вместо запуска dev-сервера в продакшене.

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

Сервер с Ubuntu 20.04 и минимум 2 ГБ оперативной памяти.
Домен, указывающий на IP сервера, например reactjs.example.com.
Доступ root или пользователь с sudo.

Обновление системы и зависимости

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

apt-get update -y

Установите необходимые утилиты:

apt-get install curl gnupg2 -y

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

По умолчанию в репозитории Ubuntu может не быть нужной версии Node.js. Добавим официальный репозиторий NodeSource (в примере — ветка 14.x):

curl -sL https://deb.nodesource.com/setup_14.x | bash -

Установите Node.js:

apt-get install nodejs -y

Обновите npm до последней версии:

npm install npm@latest -g

Проверка:

node -v

(Пример вывода: v14.x)

Установка Create React App

Create React App быстро создаёт структуру проекта и настраивает инструменты разработки.

npm install -g create-react-app

Создание первого приложения

Перейдите в /opt и создайте проект:

cd /opt
create-react-app reactproject

Запустите в режиме разработки:

cd /opt/reactproject
npm start

Это запустит dev-сервер на http://localhost:3000. Для остановки нажмите CTRL+C.

Важно: dev-сервер react-scripts предназначен для разработки и не оптимизирован для production.

Автозапуск приложения через systemd (для dev-сервера)

Если нужно, чтобы dev-сервер стартовал автоматически (обычно не рекомендуется для production), создайте systemd unit:

nano /lib/systemd/system/react.service

Вставьте:

[Service]
Type=simple
User=root
Restart=on-failure
WorkingDirectory=/opt/reactproject
ExecStart=npm start -- --port=3000

Загрузите systemd и включите сервис:

systemctl daemon-reload
systemctl start react
systemctl enable react
systemctl status react

Примечание: запуск от root не является безопасной практикой для production. Лучше создать отдельного системного пользователя и запускать от него.

Настройка Nginx как обратного прокси (dev-сервер)

Для быстрого доступа извне можно проксировать трафик с порта 80 на dev-сервер на 3000. Установите Nginx:

apt-get install nginx -y

Создайте конфигурацию виртуального хоста:

nano /etc/nginx/sites-available/reactjs.conf

Пример конфигурации, проксирующей на локальный порт 3000:

upstream backend {
  server localhost:3000;
}

server {
    listen 80;
    server_name reactjs.example.com;

    location / {
        proxy_pass http://backend/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;

        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forward-Proto http;
        proxy_set_header X-Nginx-Proxy true;

        proxy_redirect off;
    }
}

Активируйте сайт и проверьте синтаксис:

ln -s /etc/nginx/sites-available/reactjs.conf /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx
systemctl status nginx

Этот подход удобен для тестирования, но не рекомендуется для production: dev-сервер не отдаёт оптимизированные и сжатые файлы.

Production: сборка и раздача статических файлов через Nginx (рекомендуется)

Для production выполните сборку и раздавайте результат через Nginx. Это быстрее и безопаснее.

Соберите проект:

cd /opt/reactproject
npm run build

Копируйте или переместите папку build в директорию веб-сайта, например /var/www/reactproject:

mkdir -p /var/www/reactproject
cp -r build/* /var/www/reactproject/
chown -R www-data:www-data /var/www/reactproject

Настройте Nginx для раздачи статических файлов и корректной поддержки SPA (fallback на index.html):

nano /etc/nginx/sites-available/reactjs-prod.conf

Пример конфигурации:

server {
    listen 80;
    server_name reactjs.example.com;

    root /var/www/reactproject;
    index index.html index.htm;

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

    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$ {
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }
}

Активируйте и проверьте:

ln -s /etc/nginx/sites-available/reactjs-prod.conf /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

После этого приложение будет доступно по http://reactjs.example.com и обслуживаться Nginx как статические файлы.

Настройка HTTPS с Let’s Encrypt

Рекомендуется включить HTTPS. Установите certbot и плагин для Nginx:

apt-get update
apt-get install certbot python3-certbot-nginx -y
certbot --nginx -d reactjs.example.com

Certbot автоматически обновит конфигурацию Nginx и настроит редиректы с http на https. Затем проверьте автоматическое продление:

certbot renew --dry-run

Альтернативы для запуска в background (serve, PM2)

serve: лёгкий статический сервер Node.js. Установите npm i -g serve и запустите: npx serve -s build -l 3000. Можно создать systemd unit для serve.
PM2: менеджер процессов для Node.js, удобен, если нужно управлять несколькими приложениями, логированием и автоперезапуском.

Устранение неполадок

Nginx не стартует: проверьте nginx -t, затем journalctl -u nginx -b.
Ничего не отображается: убедитесь, что папка build содержит index.html и файлы стилей/скриптов.
502 Bad Gateway при проксировании: проверьте, слушает ли процесс на порту 3000 (ss -tulpn | grep 3000) и что системный юнит запущен.
Проблемы с сертификатом: проверьте что DNS указывает на ваш сервер и порт 80 доступен для проверки Let’s Encrypt.

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

Домен reactjs.example.com отвечает по HTTPS и показывает приложение.
При обращении к приложению отсутствуют ошибки 4xx/5xx в Nginx.
Файлы static (js/css) отдаются с заголовками кэширования.
Сервис автоматически перезапускается после перезагрузки сервера.

Роль‑ориентированные чеклисты

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

Проверил, что npm run build проходит без ошибок.
Проверил, что приложение работает локально в production режиме.

Системный администратор:

Настроил пользователя для сервиса, права на директорию и сервис systemd.
Настроил UFW и сертификат Let’s Encrypt.

DevOps:

Настроил CI/CD, копирование артефактов в /var/www/reactproject или автоматическую сборку на сервере.
Настроил мониторинг и ротацию логов.

Частые ошибки и как их исправить

Ошибка “Cannot GET /some-route” при перезагрузке страницы в SPA: убедитесь, что Nginx использует try_files $uri $uri/ /index.html.
Медленная загрузка: включите gzip в Nginx и добавьте кеширование для статических ресурсов.

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

Я установил и настроил окружение для React на Ubuntu 20.04: Node.js, Create React App и Nginx. Для production приложение собирается командой npm run build и обслуживается Nginx как статические файлы (root /var/www/reactproject). Настроен автоматический запуск сервисов, предложена инструкция по подключению HTTPS через Let’s Encrypt и рекомендации по безопасности (отдельный системный пользователь, UFW). Для тестирования доступен режим разработки с обратным проксированием на порт 3000. Инструкцию можно использовать как чеклист при развёртывании и подключить к CI/CD для автоматизации релизов.

Скриншот веб-интерфейса React-приложения на reactjs.example.com

Краткое резюме

Для разработки можно проксировать dev-сервер на порт 3000 через Nginx. Для production обязательно соберите проект и отдавайте статические файлы через Nginx.
Настройте HTTPS и не запускайте процессы от root.
Добавьте мониторинг и автоматизацию сборки/развёртывания.

Глоссарий в одну строку

SPA — одностраничное приложение, где маршрутизация происходит на стороне клиента.
LTS — версия Node.js с долгосрочной поддержкой.
Certbot — клиент Let’s Encrypt для автоматического получения сертификатов.

Если нужны примеры systemd unit для serve/PM2, инструкции по CI/CD или дополнительная проверка конфигурации — напишите, укажу точные файлы и команды.