Debugowanie WordPress - rozwiązywanie problemów

Zanim zaczniesz cokolwiek naprawiać, musisz zobaczyć, co tak naprawdę się psuje. Domyślnie WordPress ukrywa większość błędów PHP, zostawiając Ci tylko enigmatyczny biały ekran lub komunikat o błędzie krytycznym. Tryb debugowania zdejmuje tę zasłonę.

Otwórz plik `wp-config.php` w katalogu głównym instalacji (przez FTP, SSH albo menedżer plików w panelu hostingu) i dodaj trzy linie powyżej komentarza `/* That's all, stop editing! */`:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Każda z tych stałych robi co innego i właśnie ta kombinacja jest bezpieczna do użycia także na żywej stronie. Błędy lecą do pliku, ale nie wyświetlają się odwiedzającym ani botom Google.

Dwie ostatnie stałe są opcjonalne. `SCRIPT_DEBUG` przyda się, gdy łapiesz konflikt ze skryptami WordPressa, a `SAVEQUERIES` przy polowaniu na wolne zapytania do bazy. Pamiętaj tylko, że `SAVEQUERIES` sam w sobie obciąża serwer, więc włączaj go tylko na czas diagnozy.

Po włączeniu `WP_DEBUG_LOG` WordPress tworzy plik `wp-content/debug.log` przy pierwszym wystąpieniu błędu. Jeśli pliku nie ma, to dobry znak, że żaden błąd PHP jeszcze nie wystąpił od momentu włączenia logowania.

Otwórz log w edytorze tekstu. Każdy wpis ma datę, typ błędu oraz ścieżkę do pliku i numer linii, która go wywołała. Ta ostatnia informacja jest najcenniejsza, bo prowadzi Cię prosto do winowajcy, zwykle do konkretnej wtyczki w katalogu `/wp-content/plugins/`.

Nie wszystkie wpisy są równie groźne. Warto rozróżniać poziomy, bo log potrafi puchnąć od ostrzeżeń, które nie psują strony:

Na diagnozę awarii skup się na liniach `PHP Fatal error`. To one odpowiadają za zatrzymanie strony. Ostrzeżenia i notice odłóż na później, chyba że pojawiają się masowo i zalewają log, co samo w sobie spowalnia stronę przy każdym żądaniu.

Biały ekran śmierci (WSOD, ang. White Screen of Death) to pusta, biała strona bez żadnego komunikatu. Najczęściej oznacza błąd krytyczny PHP, który zatrzymał wykonanie skryptu, zanim WordPress zdążył cokolwiek wyświetlić. Od WordPress 5.2 zamiast pustego ekranu częściej zobaczysz komunikat *Wystąpił błąd krytyczny na tej stronie* wraz z e-mailem do administratora i linkiem do trybu odzyskiwania.

Działaj po kolei, od najmniej inwazyjnych kroków:

1. Sprawdź skrzynkę administratora. WordPress wysyła e-mail z dokładną nazwą wtyczki lub motywu, który spowodował awarię, plus link logujący w trybie odzyskiwania (recovery mode).
2. Włącz `WP_DEBUG_LOG` i zajrzyj do `debug.log`. Ostatni `Fatal error` to Twój punkt startowy.
3. Jeśli nie masz dostępu do panelu, działaj przez FTP. Zmień nazwę folderu `/wp-content/plugins/` na np. `plugins_off`, by wyłączyć wszystkie wtyczki naraz.
4. Jeśli strona wróciła, przywróć nazwę folderu i włączaj wtyczki pojedynczo, aż awaria wróci.
5. Gdy wtyczki nie są winne, przełącz motyw na domyślny (np. Twenty Twenty-Four), zmieniając nazwę folderu aktywnego motywu w `/wp-content/themes/`.

W praktyce WSOD niemal zawsze sprowadza się do trzech przyczyn: konflikt po aktualizacji wtyczki, niekompatybilna wersja PHP albo wyczerpany limit pamięci. Tę ostatnią naprawisz, dodając do `wp-config.php` linię `define('WP_MEMORY_LIMIT', '256M');`.

Błąd 500 różni się od białego ekranu tym, że generuje go serwer, a nie sam PHP WordPressa, więc `debug.log` może być pusty. Tutaj kluczowe są logi serwera, nie logi WordPressa. Znajdziesz je w panelu hostingu (sekcja Logi błędów) lub w pliku `error_log` w katalogu strony.

Najczęstsze źródła błędu 500 to uszkodzony plik `.htaccess`, przekroczony limit pamięci PHP oraz konflikt wtyczki z wersją PHP na serwerze. Poniższa tabela mapuje typowe objawy na przyczyny i rozwiązania.

Najszybszy test diagnostyczny: zmień nazwę `.htaccess` na `.htaccess_old` i odśwież stronę. Jeśli błąd zniknął, problem był w regułach przepisywania. Wejdź wtedy do panelu i zapisz ponownie strukturę odnośników, by WordPress odtworzył poprawny plik.

Gdy masz 30 wtyczek, wyłączanie ich jedna po drugiej to strata czasu. Szybsza jest metoda połowienia (bisekcji), zapożyczona wprost z debugowania kodu. Zamiast 30 prób potrzebujesz ich około pięciu.

Działa tak: wyłącz połowę wtyczek naraz. Jeśli błąd zniknął, winowajca jest w wyłączonej połowie, więc włącz ją z powrotem i wyłącz połowę tej grupy. Jeśli błąd został, sprawca jest w działającej połowie. Powtarzaj, za każdym razem dzieląc podejrzaną grupę na pół, aż zostanie jedna wtyczka. Przy 30 wtyczkach trafisz w cel po pięciu, sześciu krokach zamiast po trzydziestu.

Do izolacji bez ruszania ustawień produkcyjnych użyj wbudowanego trybu rozwiązywania problemów (Narzędzia → Kondycja witryny → Rozwiązywanie problemów). Wyłącza on wtyczki i motyw tylko dla Ciebie, podczas gdy odwiedzający widzą normalną stronę. To bezpieczniejsze niż masowe wyłączanie na żywym sklepie.

Gdy stracisz dostęp do panelu, ta sama logika działa przez FTP. Zmieniaj nazwy folderów grup wtyczek, a gdy operujesz w bazie danych, tabela `wp_options` (pole `active_plugins`) trzyma listę aktywnych wtyczek. Zawsze rób kopię tabeli przed edycją.

Ręczna edycja `wp-config.php` to podstawa, ale do głębszej analizy nieoceniona jest wtyczka Query Monitor. Pokazuje na żywym pasku każde zapytanie SQL z czasem wykonania, błędy PHP, wywołania hooków, zapytania HTTP API oraz to, która wtyczka generuje najwięcej obciążenia. Jeśli strona jest wolna, Query Monitor w kilka sekund wskaże najcięższe zapytania, których normalnie byś nie zobaczył.

Wbudowana Kondycja witryny (Narzędzia → Kondycja witryny) raportuje wersję PHP, brakujące moduły, problemy z REST API i zaplanowanymi zadaniami cron. To dobry pierwszy przystanek, zanim sięgniesz po cięższe narzędzia.

Dla sklepów osobną wartością są logi WooCommerce (WooCommerce → Status → Logi). WooCommerce zapisuje błędy krytyczne do osobnych plików `fatal-errors`, często bardziej czytelnych niż surowy `debug.log`, bo zawierają pełny ślad stosu prowadzący do konkretnej linii kodu.

Perspektywa KC Mobile: w naszych wdrożeniach utrzymaniowych najczęściej widzimy jeden powtarzalny scenariusz. Klient klika *aktualizuj wszystko* na produkcji, jedna z wtyczek nie nadąża za nową wersją PHP i strona pada. Dlatego u nas aktualizacje idą najpierw na środowisko staging, a `debug.log` sprawdzamy tam, zanim cokolwiek trafi na żywą stronę. Ta jedna zasada eliminuje większość awarii, zanim zobaczy je klient. Jeśli zależy Ci na takiej stabilności bez samodzielnego grzebania w kodzie, zajmiemy się tym w ramach budowy i opieki nad stronami internetowymi.

Tryb debugowania zostawiony na produkcji to realne ryzyko. Wyświetlane błędy (`WP_DEBUG_DISPLAY` ustawione na true) zdradzają ścieżki plików, wersje wtyczek i strukturę serwera, co jest gotową mapą dla atakującego. Dodatkowo rosnący `debug.log` potrafi spuchnąć do gigabajtów i obciążać dysk.

Gdy skończysz diagnozę, wyłącz debugowanie, zmieniając wartości na false albo usuwając dodane linie z `wp-config.php`:

define('WP_DEBUG', false);

Na koniec usuń lub opróżnij plik `wp-content/debug.log` i upewnij się, że nie jest dostępny publicznie pod adresem `twojadomena.pl/wp-content/debug.log`. Dobry hosting blokuje do niego dostęp z zewnątrz, ale warto to sprawdzić wpisując ten adres w przeglądarce. Jeśli widzisz zawartość logu, dodaj regułę blokującą w `.htaccess` albo przenieś logowanie poza katalog publiczny stałą `WP_DEBUG_LOG` ze ścieżką do pliku poza `wp-content`.

Nie chcesz grzebać w tym sam i ryzykować pogłębienia awarii? Naprawimy Twój WordPress – diagnoza w 30 minut, pełna naprawa od 299 zł, z miesięczną opieką w pakiecie.