Як виправити порожню білу сторінку у вашому застосунку

Порожня біла сторінка майже завжди означає одне з двох: JavaScript застосунку впав до того, як щось намалював, або JavaScript взагалі не завантажився. Відкрийте консоль браузера (правий клік → Inspect → Console, «Перевірити» → «Консоль») і прочитайте першу червону помилку, потім перевірте вкладку Network на файли, які не завантажилися. Більшість причин — відсутня змінна середовища, неправильний базовий шлях, незавершена збірка або збій в одному компоненті.

Цей посібник стосується односторінкових застосунків, створених з React, Vue або подібних фреймворків (включно з застосунками, створеними конструкторами на основі ШІ), бо саме там порожні сторінки трапляються найчастіше.

Чому сторінка біла

Сучасний односторінковий застосунок (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 і перезавантажте сторінку.

Дивіться на першу червону помилку; наступні часто є наслідком. Те, що вона каже, вказує на причину:

Скопіюйте повний текст помилки, включно з ім'ям файлу та номером рядка. Якщо ви користуєтесь конструктором на основі ШІ, вставте її прямо в чат.

Крок 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: Перевірте змінні середовища

Фронтенд-застосунки часто читають такі налаштування, як URL 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: Додайте межу помилок

У React один компонент, що падає, може розмонтувати весь застосунок, тому незначна помилка дає повністю порожню сторінку. Межа помилок (error boundary) — це компонент, який перехоплює помилки рендерингу всередині себе і показує резервний інтерфейс.

Додай межу помилок навколо основних маршрутів, яка показує «Щось пішло не так» з кнопкою Reload і записує помилку в консоль. Залиш заголовок і навігацію поза нею, щоб вони далі відображалися.

Вона не виправляє помилку, але відвідувачі бачать повідомлення замість порожнього екрана, а ви бачите, де саме все зламалося.

Крок 6: Немає помилок, але сторінка порожня

Якщо консоль чиста і скрипти завантажуються:

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

Порожньо лише після оновлення сторінки?

Якщо головна сторінка працює, але оновлення /dashboard дає порожню сторінку або 404, сервер не знає, що слід віддавати index.html для маршрутів застосунку. Це проблема резервного маршрутизування, описана в як виправити помилки 404 після розгортання.

Типові помилки

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

Порожні сторінки в Mythex

Якщо превью порожнє, спершу перевірте, що застосунок запущено (відкрийте Code → terminal), потім попросіть Mythex запустити правильний сервер, натисніть Refresh на панелі превью або використайте /fix. Для порожньої опублікованої URL документація радить зачекати хвилину і зробити жорстке оновлення, переконатися, що змінні середовища та база даних налаштовані перед публікацією, і перевірити ліміт вашого хостингу. Пам'ятайте, що опублікований застосунок — це знімок: після виправлення опублікуйте знову. Якщо проблему спричинила зміна, Revert to this point на останній робочій відповіді відкотить проєкт. Див. Troubleshooting і Publish troubleshooting у документації, а також наш загальний посібник як налагоджувати застосунок, створений з ШІ.

Чекліст для порожньої сторінки

• Прочитано першу червону помилку в консолі
• Перевірено вкладку Network на .js/.css файли, які дають 404 або повертають HTML
• Базовий шлях відповідає місцю, де віддається застосунок
• Збірка завершилася, і опублікована папка — це папка вихідної збірки
• Усі змінні середовища фронтенду задано в живій збірці, потім збірку виконано знову
• Збій виправлено, зокрема для порожніх і нових облікових записів
• Встановлено межу помилок, щоб майбутні збої показували повідомлення
• Є catch-all маршрут для невідомих URL
• Перевірено після жорсткого оновлення і в приватному вікні

Запитання