Белый экран React на VDS: причины и пошаговое решение

При развёртывании React-приложения на VDS с Nginx вы можете столкнуться с ситуацией, когда после сборки (npm run build) открывается белая страница, грузится бесконечно, но в консоли браузера нет ошибок, а index.html отдаёт 200. Ниже разберём самые частые причины и способы их устранения.

Почему React-приложение показывает белый экран на VDS?

Белый экран (white screen) в React обычно означает, что JavaScript-бандл не загрузился или не выполнился, но сам HTML-файл отдан корректно. Основные причины:

• Неверные пути к статическим файлам в сборке React (например, homepage в package.json или PUBLIC_URL).
• Отсутствие или неправильная настройка MIME-типов для JS/CSS в Nginx.
• Блокировка скриптов из-за Content Security Policy (CSP) или неправильных заголовков.
• Проблемы с роутингом (React Router) - когда сервер не перенаправляет все запросы на index.html.
• Ошибки в самом React-коде, которые не видны в консоли из-за source maps или тихой обработки.

Настройка Nginx для React: пошаговая инструкция

1. Проверьте корневой путь и try_files

В вашем конфиге корень указан как /var/www/html/test/dist. Убедитесь, что папка dist содержит файлы index.html, static/js/main.*.js и static/css/main.*.css. Блок location / должен работать с try_files $uri $uri/ /index.html; - это перенаправляет все запросы на index.html для поддержки SPA-роутинга. Если у вас React Router, это обязательное условие.

2. Исправьте MIME-типы для JavaScript и CSS

В вашем конфиге есть блок types и отдельный location для статики. Однако в location для статики вы принудительно задаёте add_header Content-Type "application/javascript" always; для всех файлов, включая CSS и изображения. Это ломает загрузку стилей и может привести к белому экрану. Правильнее убрать принудительный заголовок и довериться types. Используйте такой блок:

location ~* \.(js|mjs|css|png|jpg|jpeg|gif|ico|svg|woff2?|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    try_files $uri =404;
}

Убедитесь, что у вас есть include /etc/nginx/mime.types; - это стандартный файл с правильными MIME-типами. Если его нет, установите пакет nginx-extras или добавьте типы вручную:

types {
    application/javascript js mjs;
    text/css css;
}

3. Проверьте пути в сборке React

Если ваше приложение развёрнуто не в корне домена (например, по подпути), укажите "homepage": "." или "homepage": "https://site.ru" в package.json. Это влияет на генерацию путей в index.html. После изменения выполните npm run build заново.

4. Включите логирование и проверьте ошибки

Добавьте в секцию server:

error_log /var/log/nginx/react_error.log debug;

Перезагрузите Nginx (sudo nginx -s reload) и откройте страницу. Посмотрите логи - там могут быть записи о том, что файл не найден или MIME-тип неверен.

5. Проверьте консоль браузера на скрытые ошибки

Даже если в консоли нет красных ошибок, включите фильтр «Все уровни» и посмотрите вкладку Network: найдите запросы к JS/CSS файлам - они должны возвращать 200 и иметь правильный Content-Type (application/javascript, text/css). Если видите 404 или неправильный тип - проблема в путях или MIME.

Дополнительные советы

• Используйте PUBLIC_URL в скрипте сборки: PUBLIC_URL=/ npm run build (или укажите относительный путь).
• Проверьте, не блокирует ли скрипты AdBlock или расширения браузера - откройте в режиме инкогнито.
• Если используете React StrictMode, временно отключите его, чтобы исключить двойной рендер.
• Попробуйте собрать проект с GENERATE_SOURCEMAP=false - иногда source maps вызывают задержки.

Что делать, если ничего не помогло?

Попробуйте минимальную конфигурацию Nginx:

server {
    listen 80;
    server_name site.ru;
    root /var/www/html/test/dist;
    index index.html;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Если с ней всё работает - пошагово добавляйте остальные директивы, проверяя каждый раз. Также проверьте права на папку dist - они должны быть 755 для папок и 644 для файлов.