Biały ekran w WordPressie. Od logów po rozwiązanie

Otwierasz stronę po aktualizacji wtyczki, zmianie wersji PHP albo wdrożeniu poprawki i zamiast witryny widzisz pusty, biały ekran. Bez komunikatu, bez podpowiedzi i czasem nawet bez dostępu do kokpitu WordPressa. Pierwszy odruch? Cofnąć ostatnią zmianę albo zacząć wyłączać wtyczki jedna po drugiej.

Takie działania czasem przywracają stronę, ale niewiele mówią o rzeczywistej przyczynie awarii. Znacznie skuteczniejsza jest diagnostyka oparta na logach. W większości przypadków kilka minut wystarczy, aby ustalić, czy problem powoduje konkretna wtyczka, motyw, fragment własnego kodu, brak pamięci PHP czy niezgodność po zmianie środowiska.

W tym przewodniku przejdziemy przez cały proces: od sprawdzenia kodu odpowiedzi HTTP, przez error.log i debug.log, aż po bezpieczne odizolowanie przyczyny i test po naprawie. Bez zgadywania i bez wyłączania połowy strony na ślepo.

Co naprawdę oznacza biały ekran w WordPressie?

Biały ekran sam w sobie nie jest diagnozą. To jedynie objaw mówiący, że WordPress lub PHP nie wygenerowały poprawnej odpowiedzi, którą przeglądarka mogłaby wyświetlić. Przyczyn może być wiele, dlatego zamiast szukać jednego „sposobu na biały ekran”, warto najpierw ustalić, na którym etapie przetwarzania żądania pojawia się problem.

W nowszych instalacjach WordPressa część błędów krytycznych kończy się komunikatem o problemie technicznym zamiast całkowicie pustej strony. WordPress ma również wbudowany Recovery Mode. Jeśli system wykryje odpowiedni błąd krytyczny PHP, może wysłać administratorowi wiadomość z linkiem pozwalającym zalogować się w specjalnym trybie odzyskiwania.

Nie zawsze jednak mechanizm zdąży zadziałać. Błąd może wystąpić wcześniej, wiadomość może nie dotrzeć albo źródłem problemu może być konfiguracja środowiska. Dlatego podstawowym narzędziem diagnostycznym pozostają logi.

Na początek warto również sprawdzić, jaki status HTTP zwraca faktyczne żądanie do strony. Możesz wykorzystać terminal:

curl -sS -o /dev/null -w "%{http_code}\n" https://example.pl/

Jeżeli otrzymasz 500, trop prowadzi przede wszystkim do błędu po stronie aplikacji, PHP lub konfiguracji serwera. Pusty dokument z kodem 200 wymaga szerszego spojrzenia. Problem może wtedy dotyczyć motywu, mechanizmu generowania treści, cache albo kodu, który kończy wykonywanie bez wyrzucenia typowego błędu HTTP.

Zanim zaczniesz naprawiać WordPressa, zabezpiecz punkt wyjścia

Awaria nie jest dobrym momentem na wykonywanie wielu zmian jednocześnie. Jeśli wyłączysz kilka wtyczek, zmienisz PHP, podmienisz motyw i dodatkowo zmodyfikujesz wp-config.php, możesz przywrócić witrynę, ale nie będziesz wiedzieć, która operacja naprawdę pomogła. Możesz też dołożyć kolejny problem.

Przed diagnostyką wykonaj kopię plików i bazy danych albo upewnij się, że masz aktualny backup, do którego faktycznie możesz wrócić. Zanotuj również, co wydarzyło się bezpośrednio przed awarią. Aktualizacja pluginu? Wdrożenie kodu? Zmiana PHP? Import danych? Przywrócenie kopii? Taki kontekst potrafi skrócić analizę bardziej niż kilkanaście przypadkowych testów.

• zanotuj dokładną godzinę wystąpienia problemu,
• sprawdź, czy biały ekran występuje na całej stronie, tylko w /wp-admin/ czy na konkretnej podstronie,
• spróbuj odtworzyć problem w nowym oknie prywatnym,
• ustal ostatnią zmianę wykonaną przed awarią,
• upewnij się, że masz możliwość cofnięcia zmian.

Jeżeli WordPress wyświetlił komunikat o błędzie krytycznym, sprawdź również skrzynkę przypisaną do konta administratora. Tryb odzyskiwania może od razu wskazać rozszerzenie lub motyw, który zatrzymał aplikację.

Dobra praktyka. Jeśli pracujesz nad stroną klienta, zapisz godzinę każdego testu. Dzięki temu później łatwo odnajdziesz odpowiadający mu wpis w logu, nawet jeśli witryna generuje setki innych komunikatów.

Najpierw error.log. To często najszybsza droga do przyczyny

Przy białym ekranie zacznij od logu błędów serwera i PHP. error.log ma jedną ważną przewagę nad mechanizmem debugowania WordPressa: może zarejestrować problem również wtedy, gdy aplikacja nie uruchomiła się na tyle poprawnie, aby zapisać własny debug.log.

W cyber_Folks logi możesz sprawdzić bezpośrednio w panelu. W cyber_Admin przejdź do ustawień wybranej strony i sekcji z bieżącymi logami, a następnie wybierz log błędów. Dokładną ścieżkę oraz informacje o logach archiwalnych znajdziesz w instrukcji jak sprawdzić logi strony.

Teraz najważniejszy krok. Otwórz log, w drugiej karcie przeglądarki ponownie wywołaj biały ekran, a następnie odśwież log. Nie analizuj od razu każdego ostrzeżenia z ostatnich kilku dni. Szukasz przede wszystkim wpisu odpowiadającego godzinie właśnie wykonanego żądania.

Szczególnie interesujące są komunikaty zawierające:

• PHP Fatal error – błąd zatrzymał wykonywanie skryptu,
• Uncaught Error lub Uncaught TypeError – kod próbował wykonać niedozwoloną operację,
• Allowed memory size exhausted – proces wykorzystał dostępną pamięć PHP,
• Maximum execution time exceeded – skrypt wykonywał się dłużej niż zezwala konfiguracja,
• Parse error lub syntax error – PHP nie potrafi poprawnie zinterpretować kodu,
• ścieżki zawierające /wp-content/plugins/, /themes/ lub /mu-plugins/.

Wyobraź sobie taki fragment:

PHP Fatal error: Uncaught TypeError: ... in /wp-content/plugins/example-plugin/includes/class-example.php on line 214

Nie oznacza to jeszcze automatycznie, że linia 214 jest jedynym problemem. Dostajesz jednak bardzo mocny trop. Wiadomo już, że błąd pojawia się podczas wykonywania kodu konkretnej wtyczki. Kolejny krok powinien dotyczyć właśnie jej, a nie losowego wyłączania pozostałych rozszerzeń.

Podobną metodę możesz wykorzystać przy błędzie HTTP 500. Szerszy proces diagnostyczny opisujemy również w materiale WordPress – błąd 500. Jak debugować stronę?.

Gdy error.log to za mało, uruchom WP_DEBUG i debug.log

Jeżeli log serwera nie daje jednoznacznej odpowiedzi albo chcesz zobaczyć więcej komunikatów generowanych przez sam WordPress, uruchom jego mechanizm debugowania. Oficjalna dokumentacja debugowania WordPressa rozdziela trzy przydatne ustawienia: aktywację debugowania, zapisywanie komunikatów do pliku oraz ich wyświetlanie użytkownikowi.

Na stronie produkcyjnej najbezpieczniejszym wariantem jest zapis do logu bez publikowania błędów w przeglądarce:

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

Dodaj konfigurację w wp-config.php przed komentarzem kończącym część ustawień WordPressa. Jeżeli chcesz lepiej zrozumieć rolę tego pliku przed edycją, sprawdź przewodnik wp-config.php w WordPressie.

Po zapisaniu zmian ponownie wykonaj czynność prowadzącą do awarii. Standardowo komunikaty WordPressa trafią do:

/wp-content/debug.log

Dlaczego nie warto ustawiać WP_DEBUG_DISPLAY na true na działającej stronie? Komunikat może zawierać pełne ścieżki plików, fragment stosu wywołań oraz inne informacje techniczne, które nie powinny być prezentowane odwiedzającym. Log daje Ci te same tropy bez umieszczania diagnostyki na froncie.

Warto wiedzieć. Jeśli debug.log zawiera tysiące starych wpisów, zachowaj jego kopię, a następnie rozpocznij diagnostykę z czystym plikiem. Wywołaj błąd jeden raz i sprawdź świeżo wygenerowane komunikaty. Analiza stanie się znacznie prostsza.

Po zakończeniu prac wyłącz WP_DEBUG. Debugowanie jest narzędziem diagnostycznym, a nie ustawieniem, które warto pozostawiać aktywne bezterminowo. Szczegółową instrukcję dla środowiska cyber_Folks znajdziesz również w poradniku jak zdebugować WordPressa.

Jak czytać log i przejść od komunikatu do winnego elementu?

Największym błędem podczas czytania logów jest traktowanie każdego wpisu jako równie ważnego. WordPress potrafi generować ostrzeżenia i informacje, które występowały na stronie od tygodni i nie mają żadnego związku z dzisiejszą awarią.

Zamiast szukać „jakiegokolwiek błędu”, zastosuj prosty filtr. Czas → rodzaj błędu → ścieżka pliku → ostatnia zmiana.

Przy długim stack trace zacznij od właściwego błędu krytycznego i pierwszych ramek, które prowadzą do kodu strony. Nie zakładaj też, że ostatnia linia stosu wskazuje przyczynę. Często pokazuje jedynie miejsce, do którego błąd ostatecznie dotarł.

Przydatna jest również zasada jednej zmiennej. Jeśli podejrzewasz plugin, wyłącz właśnie ten plugin i ponów dokładnie ten sam test. Jeżeli strona zacznie działać, przywróć kontrolowane środowisko i ustal, czy rozwiązaniem będzie aktualizacja, rollback, poprawka konfiguracji czy zastąpienie problematycznego komponentu.

Masz SSH i WP-CLI? Diagnostykę można przyspieszyć:

wp plugin list --skip-plugins --skip-themes wp theme list --skip-plugins --skip-themes

Opcje --skip-plugins i --skip-themes bywają szczególnie przydatne, gdy normalne uruchomienie WordPressa kończy się błędem. Pamiętaj jednak, że must-use plugins wymagają osobnej uwagi. Jeżeli log wskazuje katalog mu-plugins, sprawdź go bezpośrednio.

Najczęstsze scenariusze białego ekranu i sposoby naprawy

Log wskazuje konkretną wtyczkę

Jeżeli w komunikacie błędu pojawia się jednoznaczna ścieżka do pluginu, zacznij właśnie od niego. Gdy masz dostęp do panelu, możesz go chwilowo dezaktywować. Jeśli kokpit również nie działa, skorzystaj z WP-CLI, menedżera plików lub FTP.

W awaryjnej sytuacji można zmienić nazwę katalogu konkretnej wtyczki w wp-content/plugins/. WordPress przestanie ją ładować. Rób to jednak dla pluginu wskazanego przez log, zamiast od razu zmieniać nazwę całego katalogu plugins.

Błąd prowadzi do motywu lub functions.php

Częstym źródłem awarii jest własny kod dopisany do functions.php, zwłaszcza po zmianie fragmentu PHP. Jeżeli znasz moment ostatniej modyfikacji, porównaj plik z wcześniejszą wersją i wycofaj konkretną zmianę.

Jeśli chcesz przetestować inny motyw przez WP-CLI, najpierw sprawdź dostępne motywy, a dopiero później aktywuj jeden z nich. Nie zakładaj, że na każdej instalacji znajduje się ten sam domyślny motyw.

wp theme list --skip-plugins --skip-themes 
wp theme activate NAZWA_MOTYWU --skip-plugins --skip-themes

Allowed memory size exhausted

Ten komunikat mówi wprost, że PHP próbowało wykorzystać więcej pamięci, niż miało do dyspozycji. Samo zwiększenie limitu może przywrócić witrynę, ale nie zawsze oznacza rozwiązanie przyczyny. Jeżeli jedna wtyczka nagle zaczęła konsumować setki megabajtów pamięci, warto ustalić dlaczego.

WordPress pozwala określić własny limit pamięci, na przykład:

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

Wartość nie może jednak ominąć ograniczeń narzuconych przez konfigurację PHP i hosting. Jeśli podniesienie limitu jedynie przesuwa moment wystąpienia problemu, szukaj procesu, który zużywa pamięć.

Biały ekran pojawił się po zmianie PHP

To bardzo cenna informacja diagnostyczna. Jeżeli przed zmianą wersji PHP strona działała, a chwilę później pojawił się błąd krytyczny, przywróć poprzednią konfigurację i sprawdź log. Następnie ustal, który element nie jest zgodny z docelową wersją PHP.

Nie traktuj pozostania na starej wersji jako docelowej naprawy. WordPress.org obecnie rekomenduje PHP 8.3 lub nowsze, dlatego właściwym kierunkiem jest aktualizacja problematycznego kodu, motywu lub pluginu. W środowisku cyber_Folks instrukcję zmiany znajdziesz w poradniku jak zmienić wersję PHP domeny.

Aktualne wymagania samego WordPressa możesz sprawdzić również bezpośrednio na WordPress.org. Pamiętaj przy tym, że zgodność WordPress Core nie gwarantuje zgodności każdej zainstalowanej wtyczki i każdego własnego fragmentu kodu.

Parse error po ręcznej edycji kodu

Jeśli problem pojawił się zaraz po zapisaniu zmian w functions.php, własnej wtyczce albo wp-config.php, a log pokazuje błąd składni, nie musisz reinstalować WordPressa. Cofnij ostatnią zmianę, korzystając z menedżera plików, FTP lub SSH.

Typowe przyczyny są banalne: brak średnika, niedomknięty nawias, pomylony cudzysłów albo fragment kodu wklejony w nieprawidłowym miejscu. Właśnie dlatego przed ręczną edycją pojedynczego pliku warto zrobić jego kopię.

Podejrzenie zmodyfikowanych plików WordPress Core

Jeśli wtyczki, motyw i konfiguracja PHP nie wskazują przyczyny, sprawdź integralność plików WordPressa. WP-CLI potrafi porównać pliki Core z oficjalnymi sumami kontrolnymi:

wp core verify-checksums --skip-plugins --skip-themes

Nieprawidłowy wynik nie oznacza, że należy od razu usuwać całą instalację. Najpierw ustal, które pliki różnią się od oryginału i dlaczego. Może to być efekt nieudanego wdrożenia, ręcznej modyfikacji albo incydentu bezpieczeństwa.

Strona już działa? Sprawdź, czy problem naprawdę został rozwiązany

Powrót strony głównej to dopiero pierwszy test. Jeśli naprawiasz witrynę klienta, sprawdź również najważniejsze procesy biznesowe. Awaria mogła dotyczyć kodu używanego tylko w określonej części serwisu.

• otwórz stronę główną i kilka podstron,
• zaloguj się do /wp-admin/,
• sprawdź formularz kontaktowy,
• w sklepie wykonaj test koszyka i checkoutu,
• uruchom funkcję, która wcześniej powodowała błąd,
• sprawdź ponownie error.log po wykonaniu testów,
• wyczyść odpowiednie warstwy cache, jeśli witryna z nich korzysta,
• wyłącz tymczasowe debugowanie po zakończeniu analizy.

Jeżeli zastosowałeś rollback pluginu lub wróciłeś do starszego PHP, zaplanuj również rozwiązanie docelowe. Przywrócenie starej wersji może kupić Ci czas, ale problem kompatybilności nadal istnieje i prawdopodobnie wróci przy kolejnej aktualizacji.

Warto też zapisać krótką notatkę z awarii: kiedy wystąpiła, jaki komunikat znajdował się w logu, co było przyczyną i co ostatecznie ją usunęło. Przy kolejnej podobnej sytuacji taka dokumentacja jest znacznie cenniejsza niż pamięć o tym, że „kiedyś pomogło wyłączenie jakiejś wtyczki”.

Podsumowanie. Biały ekran w WordPressie przestaje być zagadką, kiedy potraktujesz go jak proces diagnostyczny. Odtwórz problem, sprawdź godzinę, zajrzyj do error.log, w razie potrzeby uruchom debug.log, znajdź pierwszy istotny błąd i izoluj wskazany komponent. Dopiero wtedy wprowadzaj zmianę. Dzięki temu naprawiasz przyczynę, a nie tylko objaw.

Jeśli tworzysz i utrzymujesz kilka witryn, odpowiednie środowisko hostingowe ułatwia także późniejszą diagnostykę, pracę z PHP, kopiami zapasowymi i narzędziami administracyjnymi. Warto brać to pod uwagę już przy wyborze miejsca dla projektu.