Как да поправите празна бяла страница в уеб приложението си

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

Това ръководство обхваща приложения на една страница, построени с 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: Проверете променливите на средата

Фронтенд приложенията често четат настройки като 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 грешка, кодът се е сринал при рисуване. Типични причини в приложения, създадени с AI:

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

Дайте на AI пълната грешка, страницата и с кой акаунт сте влезли:

Страницата Dashboard е празна за нови потребители. Конзола: TypeError: Cannot read properties of undefined (reading 'map') в ProjectList.tsx:18. Работи за моя акаунт, който има проекти. Поправи я, така че празен акаунт да показва „Още няма проекти“, и провери нов акаунт в прегледа.

Стъпка 5: Добавете error boundary

В React един компонент, който се срине, може да размонтира цялото приложение, затова малка грешка дава напълно празна страница. Error boundary е компонент, който улавя грешки при рисуване под себе си и показва резервно съдържание.

Добави error boundary около основните маршрути, който показва „Нещо се обърка“ с бутон Презареди и записва грешката в конзолата. Остави header и навигацията извън него, за да се рисуват и при грешка.

Това не оправя грешката, но посетителите виждат съобщение, а не празен екран, а вие виждате къде се е счупило.

Стъпка 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 при последния добър отговор връща проекта назад. Вижте Отстраняване на проблеми и Отстраняване на проблеми при публикуване в документацията, както и общото ни ръководство за отстраняване на грешки в приложение, създадено с AI.

Контролен списък за празна бяла страница

• Прочетена е първата червена грешка в конзолата
• Проверени са .js/.css файловете в раздела Network, които дават 404 или връщат HTML
• Базовият път съвпада с мястото, където се сервира приложението
• Билдът е приключил и изходната папка на билда е публикуваната
• Всички променливи на средата на фронтенда са зададени в живия билд, после е направен повторен билд
• Сривът е поправен, включително за празни и нови акаунти
• Има error boundary, така че бъдещите срivове да показват съобщение
• Има catch-all маршрут за непознати URL адреси
• Тествано след принудително обновяване и в поверителен прозорец

Въпроси