Как исправить пустую белую страницу в веб-приложении

Пустая белая страница почти всегда означает одно из двух: JavaScript приложения упал до отрисовки или JavaScript вообще не загрузился. Откройте консоль браузера (правый клик → Inspect / «Просмотреть код» → Console), прочитайте первую красную ошибку, затем проверьте вкладку Network на файлы, которые не загрузились. Чаще всего причина в отсутствующей переменной окружения, неверном базовом пути, незавершённой сборке или сбое в одном компоненте.

Это руководство касается одностраничных приложений (SPA) на React, Vue или похожих фреймворках, в том числе созданных AI-конструкторами: именно там пустые страницы встречаются чаще всего.

Почему страница белая

Современное SPA отправляет браузеру почти пустой HTML-файл, примерно такой:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Затем JavaScript строит всю страницу внутри этого пустого div. Если скрипт не загрузился или выбросил ошибку до отрисовки, div остаётся пустым, и вы видите белый экран. Страница не «сломана» в каком-то видимом смысле: её просто никогда не нарисовали.

Поэтому исправление всегда начинается с инструментов разработчика, а не со самой страницы.

Шаг 1: Прочитайте консоль

Откройте инструменты разработчика: правый клик по странице и Inspect, либо F12 (Cmd+Option+I на Mac). Перейдите на вкладку Console и перезагрузите страницу.

Смотрите на первую красную ошибку: последующие часто являются следствием. Текст ошибки указывает на причину:

Скопируйте полный текст ошибки, включая имя файла и номер строки. Если вы работаете с AI-конструктором, вставьте его прямо в чат.

Шаг 2: Проверьте, что файлы загрузились

Откройте вкладку Network, включите Disable cache и перезагрузите страницу. Посмотрите на запросы к файлам .js и .css.

• Статус 404 у JavaScript-файла: страница запрашивает файл, которого нет на сервере.
• Статус 200, но тип text/html: сервер вернул страницу (часто сам index.html из-за SPA-фолбэка) вместо скрипта. Причина та же: файла нет там, где его ожидает страница.

Частые причины:

Неверный базовый путь. Если приложение открывается из подпапки, например example.com/app/, а собрано оно так, будто файлы лежат в /assets/..., все запросы скриптов промахиваются. В Vite это опция base в vite.config, в Create React App — поле homepage, в Next.js — basePath. Путь должен совпадать с тем, где приложение реально открывается.

Устаревший index.html. Инструменты сборки дают файлам имена с хешем содержимого, например index-a1b2c3.js. После нового деплоя старого файла уже нет. Если браузер или CDN всё ещё хранят старый index.html, он запрашивает несуществующий файл и ничего не получает. Жёсткое обновление (Cmd+Shift+R или Ctrl+Shift+R) подтверждает эту причину. Долгосрочное решение: отдавать index.html с коротким сроком жизни или без кэша, а файлы с хешами кэшировать надолго.

Сборка не завершилась или не была развёрнута. Если сборка упала, хостинг может отдавать старую или пустую папку. Проверьте лог сборки на ошибки.

Опубликована неверная папка. Хостинг должен отдавать результат сборки (обычно dist или build), а не папку с исходниками. Если отдать исходники, index.html будет ссылаться на /src/main.tsx, который браузер запустить не может.

Шаг 3: Проверьте переменные окружения

Фронтенд-приложения часто читают настройки вроде адреса API или публичного ключа во время сборки. Если переменной нет в боевой сборке, код вроде createClient(undefined, undefined) сразу выбрасывает ошибку, и страница становится белой.

Что важно знать:

• В Vite в браузерный код попадают только переменные с префиксом VITE_, они читаются как import.meta.env.VITE_NAME. В Create React App это REACT_APP_, в Next.js — NEXT_PUBLIC_.
• Эти значения встраиваются в код при сборке. Добавление переменной после сборки ничего не меняет, пока вы не пересоберёте и не переразвернёте приложение.
• На локальной машине или в предпросмотре может быть файл .env, которого нет в боевой сборке. Задайте те же переменные на хостинге.
• Всё с этими префиксами попадает в публичный JavaScript. Храните там только публичные значения, никогда не секретные ключи.

Быстрая проверка: ищите в тексте ошибки слово undefined рядом с названием настройки или спросите:

Опубликованное приложение показывает пустую страницу. Перечисли все переменные окружения, которые читает фронтенд, проверь, каких нет или они пустые в боевой сборке, и сделай так, чтобы при отсутствии переменной приложение показывало понятное сообщение об ошибке, а не пустую страницу.

Шаг 4: Исправьте сбой

Если в консоли обычная ошибка JavaScript, код упал во время отрисовки. Типичные причины в приложениях, созданных с ИИ:

• Данные ещё не загружены. Компонент читает user.name, пока user ещё не пришёл. Решение: состояние загрузки или optional chaining (user?.name).
• Пустые данные. У нового аккаунта нет записей, а код предполагает, что в списке есть хотя бы один элемент.
• Неожиданная структура данных. API вернул объект с ошибкой вместо списка, который ожидал код.
• Пропущенный импорт после того, как файл переименовали или переместили.
• Использование API, доступного только в браузере, при серверной отрисовке, например window или localStorage в серверном компоненте Next.js.

Дайте ИИ полную ошибку, страницу и то, под каким аккаунтом вы были залогинены:

Страница Dashboard пустая для новых пользователей. Консоль: TypeError: Cannot read properties of undefined (reading 'map') в ProjectList.tsx:18. Для моего аккаунта, в котором есть проекты, всё работает. Исправь так, чтобы пустой аккаунт показывал «Проектов пока нет», и проверь новый аккаунт в предпросмотре.

Шаг 5: Добавьте error boundary

В React один упавший компонент может размонтировать всё приложение, поэтому маленькая ошибка даёт полностью пустую страницу. Error boundary — это компонент, который перехватывает ошибки отрисовки внутри себя и вместо них показывает запасной экран.

Оберни основные маршруты в error boundary, который показывает «Что-то пошло не так» с кнопкой «Перезагрузить» и записывает ошибку в консоль. Шапку и навигацию оставь вне него, чтобы они продолжали отображаться.

Это не исправляет ошибку, но посетители видят сообщение вместо пустого экрана, а вы видите, где всё сломалось.

Шаг 6: Ошибок нет, но страница пустая

Если консоль чистая и скрипты загружаются:

• Проверьте вкладку Elements. Есть ли содержимое внутри <div id="root">? Если да, оно отрисовано, но невидимо: белый текст на белом фоне, opacity: 0, display: none или элемент на весь экран, который всё перекрывает.
• Проверьте роутер. Если ни один маршрут не подходит к текущему URL и нет маршрута «не найдено», некоторые роутеры ничего не выводят. Добавьте маршрут-заглушку, который показывает страницу 404.
• Проверьте точку монтирования. Код должен монтироваться в существующий элемент. Если в index.html есть id="app", а код ищет root, ничего не появится (и React обычно пишет об этом ошибку).
• Проверьте расширения браузера. Попробуйте приватное окно. Блокировщики рекламы иногда блокируют скрипты с именами вроде analytics или ads.

Пустая страница только после обновления?

Если главная страница работает, а обновление /dashboard показывает пустую страницу или 404, сервер не знает, что для маршрутов приложения нужно отдавать index.html. Это проблема запасного маршрута, её разбирает статья как исправить ошибки 404 после деплоя.

Частые ошибки

• Чтение последней ошибки вместо первой. Обычно причина в первой красной строке.
• Задание переменных окружения без пересборки. Переменные фронтенда фиксируются во время сборки.
• Тестирование только со своим аккаунтом. Сбои у пустых аккаунтов — одна из самых частых причин белой страницы.
• Предположение, что деплой прошёл успешно. Сначала проверьте лог сборки, а потом отлаживайте код.
• Обвинение кэша браузера во всём. Жёсткое обновление исключает кэш за секунды; если страница всё ещё пустая, причина в другом.

Пустые страницы в Mythex

Если предпросмотр пустой, сначала проверьте, что приложение запущено (откройте Code → terminal), затем попросите Mythex запустить правильный сервер, нажмите Refresh на панели предпросмотра или используйте /fix. Если пустой опубликованный адрес, документация советует подождать минуту и обновить страницу жёстким обновлением, проверить, что переменные окружения и база данных были настроены до публикации, и убедиться, что не исчерпан лимит хостинга. Помните, что опубликованное приложение — это снимок: после исправления опубликуйте его заново. Если проблему вызвало изменение, Revert to this point у последнего удачного ответа откатит проект. Подробнее см. Troubleshooting и Publish troubleshooting в документации, а также наше общее руководство по отладке приложения, созданного с ИИ.

Чек-лист по белой странице

• Прочитана первая красная ошибка в консоли
• Во вкладке Network проверены .js/.css файлы, которые дают 404 или возвращают HTML
• Базовый путь совпадает с местом, где открывается приложение
• Сборка завершилась, и опубликована именно папка с результатом сборки
• Все переменные окружения фронтенда заданы для боевой сборки, и приложение пересобрано
• Сбой исправлен, включая сценарии с пустыми и новыми аккаунтами
• Error boundary на месте, чтобы будущие сбои показывали сообщение
• Есть маршрут-заглушка для неизвестных адресов
• Проверено после жёсткого обновления и в приватном окне

Вопросы