Biała strona (WSOD) po aktualizacji wtyczki w WordPress — diagnostyka i naprawa
Poradnik techniczny · Kacper Bernecki
Biała strona (White Screen of Death) po aktualizacji wtyczki jest zwykle skutkiem fatalnego błędu PHP, konfliktu z innymi rozszerzeniami, braku pamięci lub błędnej autoload/namespace w nowej wersji wtyczki. Ten dokument opisuje uporządkowaną diagnostykę: jak włączać debug, izolować wtyczki, sprawdzać logi serwera i PHP, monitorować limity pamięci i przywrócić dostęp do panelu. Krok po kroku prowadzę przez testy, które pozwolą odtworzyć problem i bezpiecznie przywrócić działanie serwisu tak, by zminimalizować czas przestoju i utratę danych.
Jak rozpoznać przyczynę
Pierwszy kierunek to błąd PHP w plikach wtyczki: fatal error, undefined function/class lub parse error. Objawy: całkowicie pusta strona (HTTP 200 bez treści) lub komunikat błędu tylko gdy WP_DEBUG włączony. Sprawdź logi PHP/serwera i error_log hostingu; wpisy typu 'PHP Fatal error' wskażą plik i numer linii do analizy.
Drugi wariant to konflikt z innymi wtyczkami lub motywem — zamiana przestrzeni nazw, filter/action o tej samej nazwie lub różnica wersji PHP. Izolacja polega na dezaktywacji wtyczek i przełączeniu na domyślny motyw. Trzeci możliwy powód to niewystarczająca pamięć (lack of memory), wywołująca przerwanie działania procesu PHP bez komunikatu. Sprawdź limit memory_limit i zwiększ tymczasowo do 256M dla testów.
Rozwiązanie krok po kroku
1. Włącz tryb debugowania dodając w wp-config.php: define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false); Po wywołaniu strony sprawdź plik wp-content/debug.log i logi PHP hostingu pod kątem 'Fatal' lub 'Parse error' z dokładną ścieżką pliku i numerem linii.
2. Izolacja wtyczki: poprzez FTP/SFTP przejdź do wp-content/plugins i zmień nazwę katalogu problematycznej wtyczki (np. plugin-name_disabled). Jeśli strona wraca, problem jest w tej wtyczce. Jeśli nie znasz wtyczki, dezaktywuj wszystkie wtyczki przez zmianę nazwy katalogu plugins i aktywuj kolejno po jednym, obserwując moment pojawienia się błędu.
3. Sprawdź kompatybilność PHP: uruchom php -v (jeśli masz dostęp SSH) lub zapytaj hosting. Nowa wersja wtyczki może wymagać PHP 7.4/8.0+. Jeśli używasz starszej wersji, tymczasowo przełącz wersję PHP w panelu hostingu lub przywróć poprzednią wersję wtyczki.
4. Sprawdź konflikt z motywem: przełącz tymczasowo na domyślny motyw (Twenty Twenty-Three) przez bazę danych (wp_options.template, stylesheet) lub zmieniając nazwę katalogu aktywnego motywu. Jeśli problem znika, sprawdź pliki functions.php i hooki motywu.
5. Zwiększ memory_limit tymczasowo w wp-config.php lub php.ini (min. 256M) i przetestuj ponownie. Jeżeli wycinek pamieci naprawia błąd, zidentyfikuj operacje w wtyczce które zużywają dużą ilość pamięci (duże zapytania, pętle, ładowanie plików).
6. Jeżeli debug.log wskazuje konkretną linię, edytuj plik wtyczki lokalnie i sprawdź konstrukcję kodu: brakujący średnik, niezaładowany plik require_once, nieprawidłowy namespace. Przy braku kompetencji programistycznych cofnij do poprzedniej stabilnej wersji wtyczki, przywracając pliki z kopii zapasowej lub pobierając starsze wydanie.
Jak sprawdzić, czy problem zniknął
Po dezaktywacji lub przywróceniu starej wersji: otwórz kilka stron frontendu i panel administracyjny, odśwież cache przeglądarki i serwera. Sprawdź, czy HTTP odpowiada 200 oraz czy w debug.log nie pojawiają się nowe fatal errors.
Po włączeniu trybu debug i wprowadzeniu poprawki: wykonaj test obciążeniowy prostym skryptem (np. sieciowe odświeżenie kilku URL) lub ręcznie odwiedzając strony, sprawdź zużycie pamięci i czas wykonywania skryptów w narzędziach hostingu oraz czy nie ma regresji funkcji wtyczki.
W przypadku zmiany wersji PHP: przetestuj kluczowe ścieżki funkcjonalne w panelu (edytor wpisów, media upload, ustawienia wtyczki) oraz logi serwera pod kątem nowych ostrzeżeń E_DEPRECATED lub fatalnych błędów.
Czego nie robić
Nie wyłączaj WP_DEBUG_DISPLAY na produkcji bez zapisania debug.log — wyświetlanie błędów klientom ujawnia dane środowiskowe i ścieżki.
Nie usuwaj plików wtyczki ręcznie bez posiadania kopii zapasowej — utrata ustawień lub danych może być nieodwracalna. Najpierw zmień nazwę katalogu, aby dezaktywować bez usuwania.
Nie przyjmuj, że ostatnia aktualizacja jest jedyną przyczyną — zawsze zweryfikuj logi i wykonaj izolację po kolei (wtyczki, motyw, PHP, pamięć).