Biała strona (WSOD) w WordPressie: szybka ścieżka diagnostyczna

Wchodzisz na swoją stronę i widzisz nic. Dosłownie nic – czysta biel, żadnego komunikatu, żadnego kodu błędu. Przeglądarka twierdzi, że wszystko się załadowało. To WSOD, czyli White Screen of Death, i jest to jedna z najbardziej frustrujących awarii WordPressa, bo nie daje ci żadnego punktu zaczepienia.

Dobra wiadomość: WSOD prawie nigdy nie oznacza, że straciłeś dane. To zwykle błąd krytyczny PHP, który zatrzymał wykonywanie skryptu, zanim cokolwiek zdążyło się wyświetlić. Zła wiadomość: dopóki nie zobaczysz komunikatu błędu, strzelasz na ślepo.

Ten wpis to uporządkowana ścieżka diagnostyczna. Jeśli przejdziesz ją po kolei, w większości przypadków znajdziesz przyczynę w kwadrans – bez zgadywania i bez odinstalowywania połowy wtyczek na chybił trafił.

Zanim zaczniesz: dwie minuty przygotowania

Nie da się diagnozować WSOD-a bez dostępu do plików. Zanim ruszysz dalej, upewnij się, że masz:

• dostęp do plików – FTP/SFTP, menedżer plików w panelu hostingu albo SSH,
• dostęp do panelu hostingu – potrzebny do logów serwera i ustawień PHP,
• kopię zapasową – jeśli hosting robi automatyczne backupy, sprawdź, z kiedy jest najnowszy. Jeśli nie robi, zrób ją teraz, zanim zaczniesz zmieniać pliki.

Jeżeli awaria dotyczy sklepu, który właśnie przyjmuje zamówienia, i masz świeży backup sprzed problemu – czasem szybszym ruchem jest przywrócenie kopii, a diagnostyka na kopii testowej. Ale to działa tylko wtedy, gdy wiesz, co i kiedy się zmieniło.

Krok 0. Ustal zasięg awarii

To najważniejszy krok i najczęściej pomijany. Zanim cokolwiek zmienisz, sprawdź co dokładnie jest białe.

Jeśli biała jest cała strona razem z panelem, podejrzewaj uszkodzony rdzeń, wtyczkę typu must-use, wyczerpany limit pamięci PHP albo błąd w wp-config.php. Gdy front jest biały, a kokpit działa, winowajcą jest zwykle motyw lub wtyczka renderująca coś na froncie. Odwrotna sytuacja – biały panel przy działającym froncie – to klasyka tuż po aktualizacji wtyczki. Jeśli biały jest tylko koszyk albo jedna podstrona, masz najwęższy i najłatwiejszy przypadek: konkretny szablon, blok lub shortcode. A gdy biel pojawia się wyłącznie po zalogowaniu, sprawdź cache – goście dostają zbuforowaną, jeszcze sprawną wersję strony.

Sprawdź też co zmieniło się tuż przed awarią. Aktualizacja wtyczki? Nowy motyw? Zmiana wersji PHP na hostingu? Wklejony fragment kodu do functions.php? W ogromnej większości przypadków WSOD nie pojawia się sam z siebie – coś go wywołał.

Krok 1. Sprawdź skrzynkę e-mail administratora

Od WordPressa 5.2 działa mechanizm ochrony przed błędami krytycznymi (fatal error protection). Kiedy wtyczka lub motyw wywoła błąd krytyczny, WordPress wysyła na adres e-mail administratora wiadomość z:

• nazwą wtyczki lub motywu, który spowodował błąd,
• ścieżką do pliku i numerem linii,
• linkiem do trybu odzyskiwania (recovery mode).

Link do trybu odzyskiwania loguje cię do panelu z wyłączonym problematycznym rozszerzeniem. To najszybsza droga do naprawy – jeden klik zamiast grzebania w FTP.

Sprawdź też folder spam. I sprawdź, czy adres e-mail administratora w WordPressie w ogóle jest aktualny – jeśli to admin@twojadomena.pl, na który nikt nie zagląda, mechanizm jest bezużyteczny.

Jeśli dostałeś taki e-mail, masz już odpowiedź. Możesz przeskoczyć do kroku 3 lub 4 i po prostu wyłączyć wskazany element.

Krok 2. Włącz debugowanie i przeczytaj logi

Jeśli maila nie ma, musisz zmusić WordPressa, żeby powiedział ci, co się stało.

Otwórz plik wp-config.php w katalogu głównym instalacji i znajdź linię:

/* That's all, stop editing! Happy publishing. */

Powyżej niej wklej:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Jeśli któraś z tych stałych już istnieje (często WP_DEBUG jest ustawione na false), zmień jej wartość zamiast dodawać drugą definicję.

Co robi ta konfiguracja:

• WP_DEBUG włącza raportowanie błędów,
• WP_DEBUG_LOG zapisuje je do pliku wp-content/debug.log,
• WP_DEBUG_DISPLAY ustawione na false sprawia, że błędy nie wyświetlają się odwiedzającym. To ważne – nie chcesz pokazywać klientom ścieżek serwerowych ani fragmentów kodu.

Teraz odśwież stronę, która była biała, i otwórz wp-content/debug.log. Szukasz linii zaczynającej się od PHP Fatal error:. Będzie wyglądać mniej więcej tak:

PHP Fatal error:  Uncaught Error: Call to undefined function wc_get_cart_url()
in /home/user/domains/sklep.pl/public_html/wp-content/themes/moj-motyw/header.php:42

To jest twoja odpowiedź: plik, linia i przyczyna. W tym przykładzie motyw wywołuje funkcję WooCommerce, której nie ma – bo WooCommerce jest wyłączone albo zaktualizowane w sposób, który usunął tę funkcję.

Jeśli debug.log się nie utworzył

Zdarza się – najczęściej przez brak uprawnień do zapisu w wp-content albo dlatego, że błąd wystąpił zanim WordPress zdążył wczytać konfigurację debugowania. Wtedy sięgnij po logi serwera:

• w panelu hostingu poszukaj sekcji „Logi”, „Error log” albo „Dzienniki”,
• na wielu hostingach plik error_log leży bezpośrednio w katalogu strony lub public_html,
• przez SSH: tail -n 100 error_log albo tail -f error_log przy odświeżaniu strony.

Logi serwera są często bardziej wiarygodne niż debug.log, bo łapią też błędy powstałe przed startem WordPressa.

Krok 3. Wyłącz wszystkie wtyczki naraz

Jeśli logi nie wskazały jednoznacznie winowajcy, przechodzisz do metody eliminacji. Zaczynasz od wtyczek, bo to najczęstsza przyczyna.

Jeśli masz dostęp do panelu: Wtyczki → zaznacz wszystkie → Akcje zbiorcze → Wyłącz.

Jeśli panel też jest biały, zrób to przez FTP:

1. Wejdź do wp-content/.
2. Zmień nazwę folderu plugins na plugins-off.
3. Odśwież stronę.

WordPress nie znajdzie plików wtyczek i po prostu je pominie. Ustawienia wtyczek zostają w bazie danych – nic nie tracisz.

Przez WP-CLI, jeśli masz SSH:

wp plugin deactivate --all

Strona wróciła? Świetnie – winowajca to wtyczka. Przywróć nazwę folderu na plugins (wszystkie wtyczki będą teraz wyłączone) i włączaj je pojedynczo, odświeżając stronę po każdej. Ta, po której biel wraca, to twój problem.

Strona nadal biała? Wtyczki są niewinne. Idź dalej.

Krok 4. Wyklucz motyw

Ta sama logika, tylko dla motywu.

Przez FTP wejdź do wp-content/themes/ i zmień nazwę folderu aktywnego motywu – np. moj-motyw na moj-motyw-off. WordPress nie znajdzie motywu i automatycznie przełączy się na domyślny, o ile jest zainstalowany.

Jeśli domyślnego motywu nie ma w katalogu themes, pobierz go z wordpress.org i wgraj ręcznie, zanim zmienisz nazwę folderu aktywnego motywu.

Przez WP-CLI:

wp theme activate twentytwentyfour

Strona wróciła na domyślnym motywie? Problem jest w motywie. Najczęstsze przyczyny:

• błąd w functions.php – zwłaszcza jeśli ktoś ostatnio wklejał tam kod z internetu,
• motyw niekompatybilny z aktualną wersją PHP,
• niedokończona aktualizacja motywu (część plików nowa, część stara),
• motyw potomny odwołujący się do funkcji, których nie ma już w motywie nadrzędnym.

Jeśli podejrzewasz functions.php, otwórz go i sprawdź koniec pliku. Wklejone snippety lądują zwykle właśnie tam – a brakujący średnik albo podwójny znacznik zamykający ?> wystarczy, żeby położyć całą stronę.

Krok 5. Sprawdź limit pamięci PHP

Wyczerpanie pamięci to klasyczna przyczyna WSOD, szczególnie w sklepach z dużą liczbą produktów i wtyczek. W logu zobaczysz wtedy:

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted

Zwiększ limit w wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

Uwaga: WP_MEMORY_LIMIT nie może przekroczyć limitu memory_limit ustawionego na poziomie PHP przez hosting. Jeśli hosting daje 128M, wpisanie 256M w wp-config.php nic nie da. Limit PHP zmienisz w panelu hostingu (sekcja „Wersja PHP” / „Ustawienia PHP”) albo w pliku .htaccess lub php.ini, jeśli hosting na to pozwala.

Jeżeli musisz podnosić limit do 512M, żeby strona w ogóle działała, to nie jest rozwiązanie – to objaw. Coś zżera pamięć: źle napisana wtyczka, zapytanie pobierające wszystkie produkty naraz albo import, który nie został dokończony. Warto to zdiagnozować osobno.

Krok 6. Wyczyść cache – i to każdy

Bardzo częsty scenariusz: naprawiłeś przyczynę, ale strona nadal jest biała. Bo widzisz zbuforowaną wersję sprzed naprawy.

OPcache najczęściej resetuje się przy przełączeniu wersji PHP lub restarcie usługi; część hostingów ma na to osobny przycisk. Zawsze testuj efekt w trybie incognito – zaoszczędzi ci to sporo niepotrzebnego zamieszania.

Krok 7. Sprawdź integralność plików rdzenia

Jeśli doszliśmy tutaj, a strona nadal jest biała, sprawdź, czy nie uszkodziły się pliki samego WordPressa. Zdarza się to po przerwanej aktualizacji albo nieudanej migracji.

Przez WP-CLI:

wp core verify-checksums

Komenda porównuje twoje pliki z oficjalnymi sumami kontrolnymi i wypisze każdy, który się różni.

Bez WP-CLI zrób to ręcznie:

1. Pobierz WordPressa w tej samej wersji z archiwum wydań na wordpress.org.
2. Rozpakuj paczkę.
3. Wgraj przez FTP tylko foldery wp-admin i wp-includes z nadpisaniem.
4. Nie ruszaj wp-content ani wp-config.php – tam są twoje treści i konfiguracja.

To bezpieczna operacja: wp-admin i wp-includes nie zawierają twoich danych.

Przy okazji sprawdź plik .htaccess. Uszkodzony lub przepełniony regułami .htaccess częściej daje błąd 500 niż białą stronę, ale warto wykluczyć – zmień mu nazwę na .htaccess-off i odśwież. Jeśli pomogło, wygeneruj nowy: Ustawienia → Bezpośrednie odnośniki → Zapisz zmiany.

Kiedy to wcale nie jest WSOD

Biała strona bywa objawem czegoś zupełnie innego. Otwórz narzędzia deweloperskie przeglądarki (F12), przejdź do zakładki Network, odśwież stronę i sprawdź kod odpowiedzi HTTP dla głównego dokumentu.

Zerknij też do źródła strony (Ctrl+U). Jeśli widzisz pusty dokument – to WSOD. Jeśli widzisz pełny HTML, a strona i tak jest biała, problem leży w CSS lub JavaScripcie, nie w PHP. Wtedy sprawdź zakładkę Console pod kątem błędów JS i upewnij się, że pliki stylów w ogóle się ładują. Częstym sprawcą jest agresywna minifikacja i łączenie plików przez wtyczkę optymalizacyjną.

Sygnały, że to może być włamanie

Traktuj podejrzliwie sytuację, w której:

• WSOD pojawił się bez żadnej twojej zmiany,
• w katalogu głównym są pliki PHP o losowych nazwach,
• daty modyfikacji plików rdzenia są świeże, mimo że nic nie aktualizowałeś,
• w wp-config.php lub na początku plików motywu widać długie ciągi zakodowane w base64,
• pojawili się nowi użytkownicy z uprawnieniami administratora.

Wtedy diagnostyka WSOD to za mało – potrzebne jest pełne czyszczenie infekcji, wymiana wszystkich haseł i zabezpieczenie luki, przez którą ktoś wszedł. To zadanie na kompleksową naprawę awarii strony, a nie na pojedynczą poprawkę.

Specyfika WooCommerce

W sklepach WSOD ma kilka dodatkowych, typowych źródeł:

• Konflikt wtyczki płatności lub wysyłki po aktualizacji WooCommerce. Objaw jest charakterystyczny: sklep działa, ale biały jest wyłącznie koszyk albo strona zamówienia. Zawęź test do wtyczek dotykających procesu zakupowego.
• Niedokończona aktualizacja bazy WooCommerce. Po większych aktualizacjach WooCommerce uruchamia migrację danych w tle. Jeśli się przerwie, część zapytań zaczyna zwracać błędy. Sprawdź WooCommerce → Status → Narzędzia.
• Przejście na HPOS – nowy sposób przechowywania zamówień. Wtyczki niekompatybilne z HPOS potrafią wywalić panel zamówień.
• Cache na stronach transakcyjnych. Koszyk, zamówienie i konto klienta nigdy nie powinny być buforowane. Źle skonfigurowany cache daje efekt białej lub zdezaktualizowanej strony u zalogowanych klientów.
• Wyczerpanie pamięci przy eksporcie lub imporcie produktów – typowe przy dużych katalogach.

Jeśli sklep jest biały, a nie wiesz od czego zacząć: wyłącz wtyczki poza WooCommerce. To zwykle rozstrzyga sprawę w minutę.

Ścieżka diagnostyczna w skrócie

Do skopiowania i odhaczania:

1. Ustal zasięg – front, panel, jedna podstrona?
2. Sprawdź, co się zmieniło tuż przed awarią.
3. Zajrzyj do skrzynki administratora (tryb odzyskiwania).
4. Włącz WP_DEBUG_LOG i przeczytaj wp-content/debug.log.
5. Jeśli brak logu – sprawdź error_log na serwerze.
6. Wyłącz wszystkie wtyczki, potem włączaj pojedynczo.
7. Przełącz na domyślny motyw.
8. Podnieś limit pamięci PHP.
9. Wyczyść cache: wtyczka → serwer → CDN → przeglądarka.
10. Sprawdź integralność plików rdzenia.
11. Sprawdź .htaccess.
12. Wyłącz WP_DEBUG po zakończeniu.

Ostatni punkt jest obowiązkowy. Zostawienie włączonego debugowania na produkcji to wyciek informacji o strukturze serwera – dokładnie tego, czego szuka ktoś przygotowujący atak. Usuń też plik debug.log, bo bywa dostępny publicznie pod adresem twojadomena.pl/wp-content/debug.log.

Jak nie wracać do tego wpisu co miesiąc

WSOD to prawie zawsze skutek zmiany wprowadzonej bez zabezpieczenia. Cztery nawyki, które eliminują większość przypadków:

Testuj aktualizacje na staging. Kopia strony na subdomenie kosztuje niewiele, a pozwala zobaczyć błąd zanim zobaczy go klient. Większość hostingów ma tę funkcję wbudowaną.

Nie edytuj plików z poziomu panelu. Wbudowany edytor motywu nie ma cofania i nie sprawdza składni – jedna literówka w functions.php i tracisz dostęp do panelu, którym właśnie edytowałeś. Wyłącz go całkowicie:

define( 'DISALLOW_FILE_EDIT', true );

Miej działający backup i sprawdź, czy da się go przywrócić. Kopia, której nigdy nie testowałeś, to nie kopia – to nadzieja.

Ustaw aktualny adres e-mail administratora i monitoring dostępności. Chcesz się dowiedzieć o awarii z powiadomienia, a nie z telefonu od klienta.

Nie chcesz robić tego sam

Diagnostyka WSOD jest wykonalna dla każdego, kto potrafi obsłużyć FTP – ale wymaga czasu i spokoju, a jedno i drugie jest w deficycie, kiedy sklep stoi i nie przyjmuje zamówień.

Jeśli utknąłeś na którymś kroku albo po prostu wolisz oddać to komuś, kto robi to codziennie – zajmiemy się tym za ciebie. Sprawdź, jak wygląda naprawa awarii strony i sklepu internetowego: diagnozujemy przyczynę, przywracamy witrynę do działania i mówimy wprost, co ją położyło – żeby nie powtórzyło się za miesiąc.