Jak naprawić pustą białą stronę w aplikacji webowej

Pusta biała strona prawie zawsze oznacza jedną z dwóch rzeczy: JavaScript aplikacji wysypał się, zanim cokolwiek narysował, albo JavaScript w ogóle się nie załadował. Otwórz konsolę przeglądarki (prawy przycisk → Zbadaj → Konsola), przeczytaj pierwszy czerwony błąd, a potem sprawdź zakładkę Sieć pod kątem plików, które się nie załadowały. Większość przyczyn to brakująca zmienna środowiskowa, błędna ścieżka bazowa, build, który się nie skończył, albo awaria w jednym komponencie.

Ten przewodnik dotyczy aplikacji jednostronicowych (SPA) zbudowanych w React, Vue lub podobnych frameworkach (w tym aplikacji tworzonych przez narzędzia AI), bo tam puste strony są najczęstsze.

Dlaczego strona jest biała

Nowoczesna aplikacja SPA wysyła do przeglądarki prawie pusty plik HTML, mniej więcej taki:

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

JavaScript buduje następnie całą stronę wewnątrz tego pustego div. Jeśli skrypt się nie załaduje albo rzuci błąd przed renderowaniem, div pozostaje pusty i widzisz biel. Strona nie jest "zepsuta" w widoczny sposób; po prostu nigdy nie została narysowana.

Dlatego naprawa zawsze zaczyna się w narzędziach deweloperskich, a nie na samej stronie.

Krok 1: Przeczytaj konsolę

Otwórz narzędzia deweloperskie: kliknij prawym przyciskiem na stronę i wybierz Zbadaj albo naciśnij F12 (Cmd+Option+I na Macu). Przejdź do zakładki Konsola i przeładuj stronę.

Spójrz na pierwszy czerwony błąd; kolejne są często efektami ubocznymi. To, co pisze, wskazuje przyczynę:

Skopiuj pełny tekst błędu, łącznie z nazwą pliku i numerem linii. Jeśli używasz narzędzia AI do budowania, wklej go od razu do czatu.

Krok 2: Sprawdź, czy pliki się załadowały

Otwórz zakładkę Sieć, zaznacz Wyłącz pamięć podręczną (Disable cache) i przeładuj stronę. Spójrz na żądania plików .js i .css.

• Status 404 dla pliku JavaScript: strona prosi o plik, którego nie ma na serwerze.
• Status 200, ale typ to text/html: serwer zwrócił stronę (często sam index.html, przez fallback SPA) zamiast skryptu. Ta sama przyczyna: plik nie leży tam, gdzie strona go oczekuje.

Typowe powody:

Błędna ścieżka bazowa. Jeśli aplikacja działa w podfolderze, na przykład example.com/app/, ale została zbudowana tak, by ładować pliki z /assets/..., każde żądanie skryptu chybia. W Vite to opcja base w vite.config; w Create React App pole homepage; w Next.js basePath. Musi zgadzać się z tym, gdzie aplikacja faktycznie działa.

Nieaktualny index.html. Narzędzia do builda nadają plikom nazwy z hashem zawartości, np. index-a1b2c3.js. Po nowym wdrożeniu stary plik znika. Jeśli przeglądarka lub CDN nadal ma w pamięci stary index.html, prosi o stary plik i nic nie dostaje. Twarde odświeżenie (Cmd+Shift+R lub Ctrl+Shift+R) to potwierdzi. Długoterminowo serwuj index.html z krótkim lub zerowym nagłówkiem cache, a pliki z hashem trzymaj w cache długo.

Build się nie zakończył lub nie został wdrożony. Jeśli build się nie powiódł, host może serwować stary lub pusty folder wyjściowy. Sprawdź log builda pod kątem błędów.

Opublikowano zły folder. Host musi serwować wynik builda (zwykle dist lub build), a nie folder źródłowy projektu. Serwowanie źródła daje index.html, który wskazuje na /src/main.tsx — tego przeglądarka nie uruchomi.

Krok 3: Sprawdź zmienne środowiskowe

Aplikacje frontendowe często odczytują ustawienia, takie jak adres API lub publiczny klucz, w czasie builda. Jeśli zmiennej brakuje w działającym buildzie, kod w rodzaju createClient(undefined, undefined) rzuca błąd od razu i strona staje się biała.

Warto wiedzieć:

• W Vite w kodzie przeglądarki dostępne są tylko zmienne z prefiksem VITE_, odczytywane jako import.meta.env.VITE_NAZWA. W Create React App to REACT_APP_; w Next.js — NEXT_PUBLIC_.
• Te wartości są wpisywane w aplikację w czasie builda. Dodanie zmiennej po buildzie nic nie zmieni, dopóki nie zbudujesz i nie wdrożysz ponownie.
• Podgląd lub lokalna maszyna może mieć plik .env, którego nie ma produkcyjny build. Ustaw te same zmienne na hoście.
• Wszystko z tymi prefiksami trafia do publicznego JavaScriptu. Umieszczaj tam tylko publiczne wartości, nigdy klucze sekretne.

Szybki test: wyszukaj w błędzie z konsoli słowo undefined obok nazwy ustawienia albo zapytaj:

Opublikowana aplikacja pokazuje pustą stronę. Wypisz każdą zmienną środowiskową, którą czyta frontend, sprawdź, które są brakujące lub puste w działającym buildzie, i spraw, by aplikacja pokazywała wyraźny komunikat o błędzie zamiast pustej strony, gdy któraś brakuje.

Krok 4: Napraw awarię

Jeśli konsola pokazuje zwykły błąd JavaScript, kod wysypał się podczas renderowania. Typowe przyczyny w aplikacjach tworzonych z AI:

• Dane jeszcze nie załadowane. Komponent odczytuje user.name, zanim user przyszedł. Rozwiązaniem jest stan ładowania albo optional chaining (user?.name).
• Puste dane. Nowe konto nie ma rekordów, a kod zakłada, że lista ma co najmniej jeden element.
• Nieoczekiwany kształt danych. API zwróciło obiekt błędu zamiast listy, której spodziewał się kod.
• Brakujący import po zmianie nazwy lub przeniesieniu pliku.
• Użycie API dostępnego tylko w przeglądarce podczas renderowania po stronie serwera, na przykład window lub localStorage w komponencie serwerowym Next.js.

Podaj AI pełny błąd, stronę i to, na jakie konto byłeś zalogowany:

Strona Dashboard jest pusta dla nowych użytkowników. Konsola: TypeError: Cannot read properties of undefined (reading 'map') w ProjectList.tsx:18. Działa na moim koncie, które ma projekty. Napraw to, tak by puste konto pokazywało "Brak projektów", i sprawdź nowe konto w podglądzie.

Krok 5: Dodaj granicę błędów

W React jeden komponent, który się wysypie, może odmontować całą aplikację — dlatego drobny błąd daje w pełni pustą stronę. Granica błędów (error boundary) to komponent, który przechwytuje błędy renderowania poniżej siebie i pokazuje zamiast nich komunikat zastępczy.

Dodaj granicę błędów wokół głównych tras, która pokazuje "Coś poszło nie tak" z przyciskiem Przeładuj i zapisuje błąd w konsoli. Nagłówek i nawigacja mają pozostać poza nią, żeby nadal się renderowały.

Nie naprawia to błędu, ale odwiedzający widzą komunikat zamiast pustego ekranu, a Ty widzisz, gdzie się zepsuło.

Krok 6: Brak błędów, a strona nadal pusta

Jeśli konsola jest czysta i skrypty się ładują:

• Sprawdź zakładkę Elementy. Czy w <div id="root"> jest zawartość? Jeśli tak, to się renderuje, ale jest niewidoczne: biały tekst na białym, opacity: 0, display: none albo element pełnoekranowy, który to zasłania.
• Sprawdź router. Jeśli żadna trasa nie pasuje do bieżącego adresu i nie ma trasy "nie znaleziono", niektóre routery nie renderują nic. Dodaj trasę przechwytującą wszystko, która pokazuje stronę 404.
• Sprawdź punkt montowania. Kod musi montować się w elemencie, który istnieje. Jeśli index.html ma id="app", a kod szuka root, nic się nie pojawi (a React zwykle zapisze błąd).
• Sprawdź rozszerzenia przeglądarki. Spróbuj w oknie prywatnym. Blokery reklam czasem blokują skrypty o nazwach takich jak analytics czy ads.

Pusta strona tylko po odświeżeniu?

Jeśli strona główna działa, ale odświeżenie /dashboard pokazuje pustą stronę lub 404, serwer nie wie, że ma wysyłać index.html dla tras aplikacji. To problem fallbacku routingu, opisany w jak naprawić błędy 404 po wdrożeniu.

Częste błędy

• Czytanie ostatniego błędu zamiast pierwszego. Pierwsza czerwona linia to zwykle przyczyna.
• Ustawianie zmiennych środowiskowych bez przebudowy. Zmienne frontendu są stałe w czasie builda.
• Testowanie tylko na własnym koncie. Awarie dla pustych kont to jedna z najczęstszych przyczyn pustych stron.
• Zakładanie, że wdrożenie się udało. Sprawdź log builda, zanim zaczniesz debugować kod.
• Obwinianie pamięci podręcznej przeglądarki o wszystko. Twarde odświeżenie wyklucza ją w kilka sekund; jeśli strona nadal jest pusta, problem leży gdzie indziej.

Puste strony w Mythex

Jeśli podgląd jest pusty, najpierw sprawdź, czy aplikacja działa (otwórz Kod → terminal), a potem poproś Mythex o uruchomienie właściwego serwera, kliknij Odśwież na pasku narzędzi podglądu albo użyj /fix. Dla pustego opublikowanego adresu dokumentacja radzi poczekać minutę i odświeżyć z wymuszeniem, potwierdzić, że zmienne środowiskowe i baza zostały ustawione przed publikacją, i sprawdzić limit hostingu. Pamiętaj, że opublikowana aplikacja to migawka: po naprawie opublikuj ponownie. Jeśli winną była zmiana, Przywróć do tego punktu przy ostatniej dobrej odpowiedzi cofnie projekt. Zobacz Rozwiązywanie problemów i Rozwiązywanie problemów z publikacją w dokumentacji oraz nasz ogólny przewodnik jak debugować aplikację zbudowaną z AI.

Lista kontrolna pustej strony

• Przeczytano pierwszy czerwony błąd w konsoli
• Sprawdzono w zakładce Sieć pliki .js/.css, które dają 404 lub zwracają HTML
• Ścieżka bazowa zgadza się z miejscem, w którym działa aplikacja
• Build się zakończył i opublikowany jest folder wyniku builda
• Wszystkie zmienne środowiskowe frontendu ustawione w działającym buildzie, po przebudowie
• Awaria naprawiona, także dla pustych i nowych kont
• Granica błędów na miejscu, żeby przyszłe awarie pokazywały komunikat
• Trasa przechwytująca wszystko dla nieznanych adresów
• Przetestowano po twardym odświeżeniu i w oknie prywatnym

Pytania