Како да ја поправите празната бела страница во вашата веб-апликација

Празна бела страница речиси секогаш значи едно од две нешта: JavaScript на апликацијата паднал пред да нацрта било што, или JavaScript воопшто не се вчитал. Отворете ја конзолата на прелистувачот (десен клик → Inspect / Прегледај → Console / Конзола), прочитајте ја првата црвена грешка и проверете го табот Network / Мрежа за датотеки што не се вчитале. Најчестите причини се недостасувачка променлива на околината, погрешна основна патека, build што не завршил или пад во една компонента.

Овој водич ги опфаќа апликациите со една страница изградени со 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. Алатките за build им даваат на датотеките имиња со хеш на содржината, како index-a1b2c3.js. По новото распоредување, стариот датотека исчезнува. Ако прелистувачот или CDN сè уште имаат кеширан стар index.html, тој бара стара датотека и не добива ништо. Hard refresh (Cmd+Shift+R или Ctrl+Shift+R) го потврдува ова. Долгорочната поправка е да се служи index.html со кратко или без кеш заглавие, додека датотеките со хеш се кешираат долго.

Build-от не завршил или не е распореден. Ако build-от паднал, хостот можеби служи стара или празна излезна папка. Проверете го логот на build-от за грешки.

Објавена е погрешна папка. Хостот мора да служи излез од build-от (обично dist или build), а не изворната папка на проектот. Ако служите изворна папка, добивате index.html што упатува кон /src/main.tsx, а прелистувачите не можат да го извршат.

Чекор 3: Проверете ги променливите на околината

Фронтенд апликациите често читаат поставки како URL на API или јавен клуч во време на build. Ако променлива недостасува во живиот build, код како createClient(undefined, undefined) паѓа веднаш, и страницата станува бела.

Неколку работи за знаење:

• Во Vite, само променливите со префикс VITE_ се достапни во кодот на прелистувачот и се читаат како import.meta.env.VITE_NAME. Во Create React App е REACT_APP_; во Next.js е NEXT_PUBLIC_.
• Овие вредности се вградуваат при build. Додавањето променлива по build не прави ништо додека не направите build и не распоредите повторно.
• Локалната машина или прегледот може да имаат .env датотека што продукцискиот build ја нема. Поставете ги истите променливи на хостот.
• Сè со овие префикси завршува во јавниот JavaScript. Ставајте само јавни вредности таму, никогаш тајни клучеви.

Брз тест: пребарајте во грешката од конзолата undefined блиску до име на поставка, или прашајте:

Објавената апликација покажува празна страница. Наброј ги сите променливи на околината што фронтенд-от ги чита, провери кои недостасуваат или се празни во живиот build, и направи ја апликацијата да покаже јасна порака за грешка наместо празна страница кога некоја недостасува.

Чекор 4: Поправете го падот

Ако конзолата покажува нормална JavaScript грешка, кодот паднал при рендерирање. Типични причини кај апликации изградени со AI:

• Податоците уште не се вчитани. Компонента го чита user.name пред user да пристигне. Поправката е состојба на вчитување или optional chaining (user?.name).
• Празни податоци. Нова сметка нема записи, а кодот претпоставува дека листата има барем една ставка.
• Неочекуван облик на податоците. API вратил објект со грешка наместо листата што кодот ја очекувал.
• Недостасувачки импорт откако датотека е преименувана или преместена.
• Користење API што постои само во прелистувач при server-side рендерирање, како 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 околу главните рути што прикажува „Нешто тргна наопаку“ со копче 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 грешки по распоредувањето.

Чести грешки

• Читање на последната грешка наместо првата. Првата црвена линија обично е причината.
• Поставување променливи на околината без повторен build. Фронтенд променливите се фиксни во време на build.
• Тестирање само со ваша сметка. Падовите кај празни сметки се една од најчестите причини за празна страница.
• Претпоставка дека распоредувањето успеало. Проверете го логот на build-от пред да ја дебагирате целата функционалност.
• Обвинување на кешот на прелистувачот за сè. Hard refresh го исклучува тоа за неколку секунди; ако страницата е сè уште празна, проблемот е нешто друго.

Празни страници во Mythex

Ако Preview / Прегледот е празен, прво проверете дали апликацијата работи (отворете Code → terminal / Код → терминал), па побарајте од Mythex да го стартува точниот сервер, кликнете Refresh / Освежи во алатката на прегледот, или користете /fix. За празен објавен URL, документацијата предлага да почекате минута и да направите hard refresh, да потврдите дека променливите на околината и базата се поставени пред објавување, и да ја проверите вашата квота за хостинг. Имајте предвид дека објавената апликација е снимка: по поправка на нешто, објавете повторно. Ако промената предизвикала проблемот, Revert to this point / Врати на оваа точка на последниот добар одговор ја враќа проектот назад. Видете Решавање проблеми и Решавање проблеми при објавување во документацијата, и нашиот општ водич за дебагирање на апликација изградена со AI.

Контролна листа за празна страница

• Прочитана првата црвена грешка во конзолата
• Проверени табот Network за .js/.css датотеки што даваат 404 или враќаат HTML
• Основната патека се поклопува со местото каде што се служи апликацијата
• Build-от завршил, а излезната папка од build-от е онаа што се објавува
• Сите фронтенд променливи на околината се поставени на живиот build, па направен повторен build
• Падот е поправен, вклучително и за празни и нови сметки
• Error boundary е на место, па идните падови покажуваат порака
• Catch-all рута за непознати URL-а
• Тестирано по hard refresh и во прозорец за приватно сурфање

Прашања