Как раздать React SPA через Nginx: полное руководство

Введение

React SPA (Single Page Application) — это приложение, которое загружается один раз и далее работает на стороне клиента, используя JavaScript для маршрутизации. При раздаче такого приложения через Nginx важно правильно настроить сервер, чтобы все маршруты (например, /about, /dashboard) возвращали один и тот же index.html, а статические ресурсы (JS, CSS, изображения) отдавались с правильными заголовками кэширования. В этом руководстве мы рассмотрим полный процесс: от сборки React-приложения до настройки Nginx с поддержкой HTTPS и оптимизацией производительности.

Требования

• Сервер с установленным Nginx (версия 1.18+).

• Node.js и npm (для сборки React-приложения).

• Собранное React-приложение (папка build или dist).

• Доступ к конфигурационным файлам Nginx (обычно /etc/nginx/).

• Базовые знания командной строки.

Шаг 1: Сборка React-приложения

Перед настройкой Nginx необходимо собрать ваш React-проект в статические файлы. В большинстве случаев используется Create React App (CRA) или Vite.

1. Перейдите в корневую папку проекта. 2. Выполните команду сборки:

- Для CRA: npm run build

- Для Vite: npm run build 3. После успешной сборки появится папка build (CRA) или dist (Vite) с файлами index.html, static/js/, static/css/ и другими ресурсами.

Важно: убедитесь, что в package.json указан homepage (для CRA) или base (для Vite), если приложение будет размещено в поддиректории. Для корня сайта это не требуется.

Шаг 2: Копирование файлов на сервер

Перенесите собранные файлы на сервер. Можно использовать scp, rsync или Git.

Пример с rsync:

rsync -avz build/ user@your-server:/var/www/react-app/

Создайте директорию, если её нет:

sudo mkdir -p /var/www/react-app
sudo chown -R $USER:$USER /var/www/react-app

Шаг 3: Базовая конфигурация Nginx

Создайте новый конфигурационный файл в /etc/nginx/sites-available/react-app:

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

    root /var/www/react-app;
    index index.html;

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

Активируйте сайт:

sudo ln -s /etc/nginx/sites-available/react-app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Пояснение: директива try_files пытается найти запрошенный файл, затем директорию, и если ничего не найдено, возвращает index.html. Это ключевой момент для SPA.

Шаг 4: Настройка обработки маршрутов React Router

React Router использует History API, поэтому при переходе по ссылке /about сервер должен вернуть index.html, а не 404. Директива try_files из предыдущего шага уже решает эту проблему. Однако есть нюансы:

• Если вы используете BrowserRouter, убедитесь, что все запросы к несуществующим файлам перенаправляются на index.html.

• Если в приложении есть статические файлы с расширениями (например, .js, .css), они должны отдаваться напрямую.

Дополнительно можно добавить обработку для API-запросов, если они проксируются на бэкенд:

location /api/ {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Шаг 5: Кэширование статических ресурсов

Для ускорения загрузки настройте кэширование для статических файлов. Добавьте в конфигурацию:

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    access_log off;
}

Это позволит браузеру кэшировать ресурсы на год. Убедитесь, что имена файлов содержат хэш (например, main.abc123.js), чтобы избежать проблем при обновлении.

Шаг 6: Настройка сжатия Gzip

Включите сжатие для уменьшения размера передаваемых данных:

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
gzip_min_length 1000;
gzip_comp_level 6;
gzip_vary on;

Эти настройки можно разместить в блоке http или в server.

Шаг 7: Настройка HTTPS с Let's Encrypt

Для безопасности используйте HTTPS. Установите Certbot:

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

Certbot автоматически изменит конфигурацию Nginx, добавив SSL-сертификаты и перенаправление с HTTP на HTTPS. После этого проверьте конфигурацию:

sudo nginx -t
sudo systemctl reload nginx

Шаг 8: Оптимизация производительности

Дополнительные меры для улучшения производительности:

• HTTP/2: включите в блоке listen: listen 443 ssl http2;

• Кэширование на стороне клиента: используйте etag и if-none-match.

• Предзагрузка: добавьте preload для критических ресурсов.

• Балансировка: если у вас несколько экземпляров приложения, настройте upstream.

Пример с HTTP/2:

server {
    listen 443 ssl http2;
    ...
}

Шаг 9: Проверка и отладка

После настройки проверьте работу приложения:

1. Откройте сайт в браузере. 2. Перейдите по внутренним ссылкам (например, /about) — страница должна обновиться без 404. 3. Проверьте кэширование: откройте DevTools → Network, убедитесь, что статические файлы имеют заголовок Cache-Control: public, immutable. 4. Проверьте HTTPS: убедитесь, что сайт доступен по https:// и есть перенаправление с HTTP.

Если что-то не работает, проверьте логи Nginx:

sudo tail -f /var/log/nginx/error.log

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

1. 404 при обновлении страницы — забыли try_files $uri $uri/ /index.html;. 2. Неправильные пути к статике — если приложение в поддиректории, нужно настроить homepage в package.json и root в Nginx. 3. Кэширование index.html — не кэшируйте index.html, иначе пользователи не увидят обновления. Добавьте для него expires -1; или add_header Cache-Control "no-cache";. 4. Ошибки CORS — если API на другом домене, настройте проксирование или CORS-заголовки. 5. Проблемы с HTTPS — неправильные пути к сертификатам или отсутствие перенаправления.

FAQ

Вопрос: Нужно ли настраивать try_files для всех location? Ответ: Нет, только для основного location /. Для статики используйте отдельные блоки с кэшированием.

Вопрос: Как раздать SPA в поддиректории? Ответ: Укажите homepage в package.json (например, "homepage": "/myapp"), соберите проект и в Nginx используйте location /myapp { alias /var/www/react-app; try_files $uri $uri/ /myapp/index.html; }.

Вопрос: Почему после обновления приложения пользователи видят старую версию? Ответ: Скорее всего, index.html кэшируется. Установите для него Cache-Control: no-cache.

Вопрос: Как настроить проксирование API? Ответ: Добавьте location /api/ { proxy_pass http://backend; } и убедитесь, что бэкенд доступен.

Вопрос: Нужен ли root или alias? Ответ: Для корня сайта используйте root. Для поддиректории — alias.

Итог

Настройка Nginx для React SPA — это несколько ключевых шагов: сборка приложения, копирование файлов, базовая конфигурация с try_files, кэширование статики, сжатие и HTTPS. Следуя этому руководству, вы сможете развернуть производительное и безопасное SPA. Не забывайте проверять конфигурацию через nginx -t и следить за логами. Удачи!