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

React SPA — это одностраничное приложение, которое после сборки превращается в набор статических файлов: HTML, JavaScript, CSS и медиа. Чтобы пользователи могли открывать любые маршруты (например, /dashboard или /profile/123) и при этом не получать 404, сервер должен всегда отдавать index.html, а маршрутизацию берёт на себя React Router. В этом руководстве мы разберём, как правильно настроить Nginx для раздачи React SPA в production: от сборки проекта до HTTPS и кэширования.

Требования

Перед началом убедитесь, что у вас есть:

• Сервер на Linux (Ubuntu 20.04+ или Debian 11+).

• Установленный Node.js (версия 16 или выше) и npm/yarn.

• Установленный Nginx (если нет — установите командой sudo apt install nginx).

• Доменное имя, указывающее на IP сервера (для HTTPS).

• Права sudo для редактирования конфигураций.

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

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

npm run build

Если вы используете Create React App, Vite или Next.js (в режиме статического экспорта), результат появится в папке build или dist. Убедитесь, что в корне сборки есть файл index.html.

Скопируйте содержимое сборки на сервер, например, в /var/www/myapp:

sudo mkdir -p /var/www/myapp
sudo cp -r build/* /var/www/myapp/

Установите правильные права: файлы должны быть доступны для чтения пользователю nginx (обычно www-data).

sudo chown -R www-data:www-data /var/www/myapp
sudo chmod -R 755 /var/www/myapp

Шаг 2: Создание конфигурации Nginx

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

sudo nano /etc/nginx/sites-available/myapp

Вставьте базовую конфигурацию:

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

    root /var/www/myapp;
    index index.html;

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

Ключевой момент — директива try_files $uri $uri/ /index.html;. Она пытается отдать запрошенный файл, затем директорию, а если ничего не найдено — отдаёт index.html. Это и есть основа для работы React Router.

Активируйте сайт и перезагрузите Nginx:

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

Шаг 3: Настройка кэширования статики

Статические файлы (JS, CSS, изображения) имеют хеши в именах, поэтому их можно кэшировать надолго. Добавьте в конфигурацию:

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

Для index.html кэш лучше отключить, чтобы пользователи получали свежую версию:

location = /index.html {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    expires 0;
}

Шаг 4: Включение gzip-сжатия

Сжатие уменьшает размер передаваемых файлов. В блоке http (обычно в /etc/nginx/nginx.conf) или внутри server добавьте:

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

Проверьте конфигурацию и перезагрузите Nginx.

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

Установите Certbot:

sudo apt install certbot python3-certbot-nginx

Запустите получение сертификата:

sudo certbot --nginx -d example.com -d www.example.com

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

sudo certbot renew --dry-run

Шаг 6: Обработка ошибок и логирование

Убедитесь, что Nginx пишет логи в удобные файлы. В блоке server можно указать:

access_log /var/log/nginx/myapp.access.log;
error_log /var/log/nginx/myapp.error.log;

Для отладки проблем с маршрутизацией проверяйте эти логи.

Шаг 7: Проверка работы SPA

Откройте браузер и перейдите по адресу https://example.com. Затем попробуйте открыть прямой URL, например https://example.com/about. Если страница отображается корректно — всё работает. Если вы видите 404, проверьте, что директива try_files присутствует и путь к index.html верный.

Шаг 8: Дополнительные настройки безопасности

Добавьте базовые заголовки безопасности:

add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Referrer-Policy "strict-origin-when-cross-origin";

Если приложение использует API на том же домене, настройте проксирование:

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

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

1. Отсутствие `try_files` — при прямом переходе на внутренний маршрут Nginx возвращает 404. Решение: добавить try_files $uri $uri/ /index.html;. 2. Неправильные права доступа — Nginx не может прочитать файлы. Убедитесь, что владелец — www-data и права 755. 3. Кэширование `index.html` — пользователи видят старую версию приложения. Отключите кэш для index.html. 4. Отсутствие gzip — медленная загрузка. Включите gzip для текстовых файлов. 5. Ошибки в путях — если сборка лежит в подпапке, нужно настроить homepage в package.json и base в конфигурации роутера. 6. Игнорирование HTTPS — современные браузеры могут блокировать некоторые функции. Используйте Let's Encrypt.

FAQ

Вопрос: Почему при обновлении страницы появляется 404? Ответ: Потому что Nginx ищет файл по пути, которого нет. Директива try_files решает эту проблему, перенаправляя все запросы на index.html.

Вопрос: Нужно ли настраивать CORS? Ответ: Если API находится на другом домене, да. Но если вы проксируете API через Nginx, CORS не требуется.

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

Вопрос: Можно ли использовать HTTP/2? Ответ: Да, при настройке HTTPS добавьте listen 443 ssl http2;.

Вопрос: Как проверить, что gzip работает? Ответ: Используйте curl -H "Accept-Encoding: gzip" -I https://example.com и проверьте наличие заголовка Content-Encoding: gzip.

Итог

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