Jak naprawić biały ekran śmierci (White Screen of Death) w WordPress

Wstęp – czym jest biały ekran śmierci w WordPress

Biały ekran śmierci, czyli White Screen of Death (WSOD), to sytuacja, w której Twoja strona WordPress wyświetla kompletnie pustą stronę. Żadnego nagłówka, treści, stopki. Żadnego komunikatu. Strona po prostu nie istnieje z punktu widzenia przeglądarki, choć technicznie PHP wykonało się do pewnego momentu i przerwało.

Od wersji WordPress 5.2 (kwiecień 2019) większość krytycznych błędów PHP nie kończy się już czystą białą stroną. WordPress ma wbudowany mechanizm – WP_Fatal_Error_Handler – który łapie błąd, zwraca HTTP 500 i wyświetla komunikat „There has been a critical error on this website". Do tego wysyła maila z linkiem do trybu awaryjnego. Jeśli widzisz właśnie taki komunikat, Twój problem jest łatwiejszy: kliknij link z maila, zaloguj się, dezaktywuj wadliwą wtyczkę.

Prawdziwy, klasyczny biały ekran oznacza, że błąd PHP wystąpił tak wcześnie, że WordPress nie zdążył uruchomić własnego mechanizmu ratunkowego. Albo dzieje się to w kontekście, do którego ten mechanizm nie ma dostępu. Brzmi groźnie, ale w praktyce sprowadza się do kilku konkretnych przyczyn, które można zdiagnozować i naprawić bez paniki.

Najczęstsze przyczyny białego ekranu śmierci

Dane z realnych zgłoszeń pokazują wyraźny rozkład. Według analiz zebranych z kilku źródeł utrzymujących setki stron WordPress:

Aktualizacja wtyczki to przyczyna około 45% przypadków. To najczęstszy scenariusz. Wtyczka aktualizuje się w nocy przez auto-update, a rano strona nie żyje. Albo sam klikasz „aktualizuj wszystko" i nagle robi się biało.

Zmiana wersji PHP odpowiada za około 20%. Twój hosting mógł przeskoczyć z PHP 7.4 na 8.x bez wyraźnego komunikatu. Wtyczki nieaktualizowane od lat przestają działać, bo funkcje, których używają, zostały usunięte z nowszego PHP.

Wyczerpanie limitu pamięci to około 15%. Strona robiła się coraz cięższa, dokładałeś kolejne wtyczki, a limit pamięci został na domyślnym poziomie 40 MB. W końcu PHP powiedziało „dość".

Błąd w plikach motywu – około 10%. Najczęściej po ręcznej edycji pliku functions.php. Brakujący średnik, niedomknięty nawias, wywołanie funkcji, która nie istnieje.

Uszkodzone pliki rdzenia WordPressa (około 5%), zwykle po przerwanej aktualizacji. I problemy z bazą danych lub hostingiem (kolejne 5%).

Zauważ, czego nie ma na tej liście: „wyczyść cache", „zainstaluj WordPress od nowa", „sprawdź plik .htaccess". To nie są najczęstsze przyczyny. Wbrew temu, co mówi wiele poradników, nie zaczynaj od nich.

Jak zdiagnozować problem – metody, które faktycznie działają

Zanim cokolwiek ruszysz: sprawdź HTTP status

Weź narzędzie developerskie (albo zwykły curl w terminalu) i sprawdź, co serwer zwraca.

• HTTP 500 oznacza błąd krytyczny PHP. To prawdopodobnie WSOD.
• HTTP 504 to timeout serwera – proces PHP wisi lub jest zakleszczony, to inny problem.
• HTTP 503 oznacza tryb konserwacji. Sprawdź, czy w katalogu głównym nie ma pliku .maintenance.
• HTTP 200 z pustym ciałem to najgorszy wariant. Żądanie „się powiodło", ale PHP nie wygenerowało żadnej treści. Zwykle błąd przed pierwszym bajtem przy wyłączonym wyświetlaniu błędów.

Włącz debugowanie WordPressa

Podłącz się przez SFTP do serwera, otwórz plik wp-config.php. Znajdź linię definiującą stałą WP_DEBUG ustawioną na false.

Zmień jej wartość na true, a tuż przed komentarzem „That's all, stop editing!" dodaj dodatkowo włączenie zapisu do logu (WP_DEBUG_LOG ustawione na true), wyłączenie wyświetlania błędów na stronie (WP_DEBUG_DISPLAY ustawione na false) oraz wywołanie ini_set wyłączające display_errors.

Włączasz tryb debugowania, każesz WordPressowi zapisywać błędy do pliku, ale nie pokazywać ich na stronie. Odwiedzający nic nie zobaczą, a Ty dostaniesz log.

Zapisz plik, odśwież stronę, która jest biała, a potem otwórz plik wp-content/debug.log. Zobaczysz tam wpis w formacie: data i godzina w nawiasie kwadratowym, a po niej komunikat w stylu "PHP Fatal error: Uncaught Error: Call to undefined function my_custom_function()" wraz z pełną ścieżką do pliku, np. wp-content/themes/my-theme/functions.php, i numerem linii, np. 42.

Ścieżka pliku i numer linii mówią Ci, co jest nie tak. To najważniejsza umiejętność w diagnozowaniu WSOD – przeczytanie stack trace'a i zrozumienie, na co wskazuje.

Co zrobić, gdy debug.log się nie tworzy

Są trzy powody, dla których plik debug.log może nie powstać.

Po pierwsze, hosting nadpisał domyślną ścieżkę logu – sprawdź panel hostingu. Po drugie, proces PHP nie ma uprawnień do zapisu w katalogu wp-content. Po trzecie, błąd występuje w pliku wp-config.php – zanim WordPress zdążył ustawić debug logging.

W trzecim przypadku możesz dodać na samym początku wp-config.php tymczasowo wywołania ini_set włączające display_errors oraz error_reporting ustawione na E_ALL.

Odśwież stronę – błąd pokaże się w przeglądarce. Jak tylko go odczytasz, natychmiast usuń te linie. Zostawienie display_errors włączonego na produkcji to ryzyko bezpieczeństwa.

Sprawdź logi serwera

Jeśli debug.log jest pusty i nie masz podejrzenia, że błąd jest w wp-config.php, sprawdź logi PHP i serwera WWW. U większości hostingów znajdziesz je w panelu administracyjnym („Error Logs", „PHP Error Log"). Na własnym serwerze szukaj w plikach error.log w katalogach php-fpm lub apache2 wewnątrz /var/log. To tam trafiają błędy, które wystąpiły zanim WordPress w ogóle zaczął się uruchamiać.

Jak naprawić biały ekran – konkretne kroki

Po przeczytaniu logu wiesz już, co jest nie tak. Albo – jeśli log jest pusty – wiesz przynajmniej, że błąd jest na poziomie serwera. Przejdźmy przez kroki naprawcze w kolejności, która ma sens.

Krok 1: Dezaktywuj wszystkie wtyczki

Jeśli log wskazuje na konkretną wtyczkę, sprawa jest prosta. Jeśli nie wiesz, która jest winna, dezaktywuj wszystkie naraz.

Przez FTP/SFTP: zmień nazwę katalogu wp-content/plugins na wp-content/plugins-off. WordPress przestanie widzieć wtyczki. Jeśli strona wróciła, przywróć oryginalną nazwę katalogu, a potem zmieniaj nazwy poszczególnych podkatalogów wtyczek jeden po drugim, aż znajdziesz sprawcę.

Przez WP-CLI (jeśli masz dostęp SSH): polecenie dezaktywujące wszystkie wtyczki naraz, potem włączaj je pojedynczo.

Przez bazę danych: w phpMyAdmin lub Adminer wykonaj zapytanie SQL aktualizujące wpis active_plugins w tabeli wp_options na pustą tablicę serializowaną.

To opróżnia tablicę aktywnych wtyczek. Potem możesz włączać je z poziomu panelu administracyjnego.

Krok 2: Przełącz na domyślny motyw

Jeśli dezaktywacja wtyczek nie pomogła, podejrzanym numer dwa jest motyw. Zmień nazwę katalogu motywu w folderze wp-content/themes. WordPress automatycznie przełączy się na domyślny motyw (Twenty Twenty-Five lub podobny). Jeśli strona wraca do życia – problem jest w motywie.

Jeśli nie masz zainstalowanego domyślnego motywu, możesz wymusić go przez dodanie do wp-config.php stałej WP_DEFAULT_THEME ze wskazaniem nazwy motywu, np. twentytwentyfive.

Krok 3: Zwiększ limit pamięci

Jeśli log pokazuje „Allowed memory size of X bytes exhausted", PHP zabrakło pamięci. Domyślny limit w WordPressie to 40 MB dla pojedynczej instalacji i 64 MB dla multisite. To mało, szczególnie jeśli używasz page buildera, WooCommerce albo kilkunastu wtyczek.

Dodaj do wp-config.php dwie stałe: WP_MEMORY_LIMIT ustawioną np. na 256M oraz WP_MAX_MEMORY_LIMIT ustawioną np. na 512M.

WP_MEMORY_LIMIT dotyczy frontendu strony, WP_MAX_MEMORY_LIMIT – panelu administracyjnego. Pamiętaj jednak: WordPress nie może ustawić sobie więcej pamięci, niż pozwala serwer. Jeśli hosting ma w php.ini ustawiony limit pamięci na poziomie 128M, to podniesienie WP_MEMORY_LIMIT do 512M nic nie da. W takiej sytuacji zmień wartość memory_limit w php.ini lub .user.ini, albo skontaktuj się z hostingiem.

Zalecane wartości: prosty blog 128 MB, strona z page builderem 256 MB, sklep WooCommerce 256–512 MB, strona członkowska z wieloma wtyczkami 512 MB i więcej.

Krok 4: Sprawdź plik .htaccess

Uszkodzony plik .htaccess to częsta przyczyna błędu 500, który wygląda jak biały ekran. Przy problemach z .htaccess debug.log będzie pusty – błąd dzieje się na poziomie serwera WWW.

Zmień nazwę pliku .htaccess na .htaccess-backup. Odśwież stronę. Jeśli wróciła – sprawa jasna. Wejdź w panel administracyjny, przejdź do Ustawienia → Bezpośrednie linki i kliknij „Zapisz zmiany". WordPress wygeneruje nowy, czysty plik.

Krok 5: Wyczyść OPcache

To pułapka, która łapie nawet doświadczonych. Edytujesz plik, zapisujesz poprawkę, odświeżasz – a strona dalej pusta. Sprawdzasz plik, poprawka jest. Log nie pokazuje nowych błędów. Strona dalej biała.

Winowajcą jest OPcache. PHP cache'uje skompilowany kod w pamięci, żeby nie kompilować go przy każdym żądaniu. Jeśli serwer ma wyłączoną walidację znaczników czasu (opcja opcache.validate_timestamps ustawiona na 0, częste na produkcji), to edycja pliku na dysku nie jest widziana przez PHP. Ono dalej wykonuje starą, zepsutą wersję.

Rozwiązania: zrestartuj PHP-FPM poleceniem service dla odpowiedniej wersji PHP z parametrem reload, wywołaj reset OPcache funkcją opcache_reset z poziomu PHP, albo użyj przycisku w panelu hostingu. Większość zarządzanych hostingów ma opcję „clear PHP OPcache". Jeśli nie masz dostępu do restartu, pomóc może zmiana znacznika czasu pliku poleceniem touch na pliku wp-config.php.

Krok 6: Przywróć pliki rdzenia WordPress

Jeśli nadal nie wiesz, co jest nie tak, możesz mieć uszkodzone pliki po nieudanej aktualizacji. Przez WP-CLI wystarczy polecenie pobierające najnowsze pliki rdzenia z pominięciem zawartości i wymuszające nadpisanie (odpowiednik wp core download z flagami --skip-content i --force).

To pobiera świeże pliki WordPressa i nadpisuje istniejące, nie ruszając katalogu wp-content.

Krok 7: Baza danych i tryb konserwacji

WordPress mógł utknąć w trybie konserwacji po przerwanej aktualizacji. Sprawdź, czy w katalogu głównym nie ma pliku .maintenance. Jeśli jest – usuń go.

Problemy z bazą danych rzadko powodują czysty biały ekran (zwykle dają komunikat „Error establishing a database connection"), ale jeśli podejrzewasz bazę, uruchom naprawę. Dodaj do wp-config.php stałą WP_ALLOW_REPAIR ustawioną na true.

Wejdź na adres swojej strony z dopisaną ścieżką /wp-admin/maint/repair.php. Po naprawie natychmiast usuń tę linię – to ryzyko bezpieczeństwa.

Kiedy Recovery Mode nie działa

WordPress 5.2 wprowadził mechanizm ochrony przed błędami krytycznymi. Gdy wykryje błąd, wysyła maila z linkiem do trybu awaryjnego. Link działa przez godzinę (domyślnie), a po jego kliknięciu możesz zalogować się do panelu z automatycznie wyłączoną wadliwą wtyczką lub motywem.

Brzmi świetnie, ale ma ograniczenia.

Mail może nie dotrzeć – jeśli Twoja strona nie wysyła maili (brak SMTP, zawodny PHP mail()), link nigdy nie trafi do Ciebie. Albo adres email administratora jest nieaktualny. Jeśli w ustawieniach WordPressa jest stary adres, na który nie masz dostępu, nie ma linku.

Błąd może być też zbyt wczesny. Jeśli problem leży w wp-config.php, must-use pluginie lub drop-inie (jak object-cache.php), Recovery Mode w ogóle się nie uruchomi. WordPress nie zdążył załadować mechanizmu ochronnego.

I sytuacja rekurencyjna: zepsuta jest wtyczka od SMTP. Ta, która miała wysłać maila o błędzie, sama jest źródłem błędu.

Dlatego ręczne metody – FTP, WP-CLI, debug.log – są niezbędne.

Specyficzne problemy na zarządzanych hostingach

Jeśli korzystasz z zarządzanego hostingu WordPress, niektóre problemy mogą mieć inne podłoże.

Kinsta automatycznie wyłącza wtyczki uznawane za zagrożenie bezpieczeństwa. Sprawdź zakładkę „Security" w MyKinsta.

WP Engine ma bloker cron i własny object cache drop-in, który może kolidować z niektórymi wtyczkami.

Cloudways używa Varnish przed Nginx. Błędna konfiguracja Varnish może serwować zapisaną w cache pustą stronę bezterminowo.

Pantheon ma system plików tylko do odczytu na produkcji. Nie edytuj plików bezpośrednio – deploy idzie przez Git.

Jak zapobiec białemu ekranowi

Biały ekran da się naprawić w kilkanaście minut, jeśli wiesz, co robić. Ale jeszcze lepiej mu zapobiegać.

Środowisko stagingowe to podstawa. Każdy porządny hosting daje je za darmo. Aktualizuj wtyczki najpierw tam, kliknij po stronie, sprawdź logi. Potem wgrywaj na produkcję. To samo eliminuje większość problemów z aktualizacji.

Monitoring z zewnątrz – nie „strona wygląda dobrze", ale faktyczne sprawdzanie z usługi takiej jak UptimeRobot czy BetterStack, które walidują nie tylko kod odpowiedzi, ale też czy ciało odpowiedzi nie jest puste.

I jedno ustawienie, które powinieneś włączyć raz i zapomnieć: WP_DEBUG_LOG zawsze aktywne, WP_DEBUG_DISPLAY zawsze wyłączone. Nawet na produkcji. Log jest tani, wyświetlanie błędów na stronie jest ryzykowne. Gdy problem wystąpi, dane już czekają.

Do tego regularne kopie zapasowe, audyt wtyczek (usuwanie tych nieaktualnych od ponad roku) i ustawienie rozsądnego limitu pamięci od razu, nie w momencie awarii. I zasada, której nigdy nie łam: nie edytuj plików PHP bezpośrednio w panelu administracyjnym WordPressa. Jedna literówka w functions.php i cała strona leży.

Praktyczna kolejność działania

Gdy widzisz biały ekran, nie panikuj i nie reinstaluj WordPressa na ślepo. Działaj w tej kolejności:

1. Sprawdź skrzynkę mailową – czy nie dostałeś linku z Recovery Mode.
2. Włącz WP_DEBUG_LOG w wp-config.php.
3. Otwórz wp-content/debug.log i znajdź „Fatal error" – ścieżka pliku wskaże winowajcę.
4. Log wskazuje wtyczkę? Dezaktywuj przez FTP lub WP-CLI.
5. Wskazuje motyw? Przełącz na domyślny.
6. Mówi o pamięci? Zwiększ limit.
7. Log jest pusty? Sprawdź .htaccess, OPcache i logi serwera.

Biały ekran wygląda dramatycznie, ale zawsze jest jednym z kilku typowych problemów. Najpierw zdobądź informację – log powie Ci, co jest grane.