Masz problem z błędami na stronie i nie wiesz, jak ugryźć debugowanie WordPress? Z tego poradnika dowiesz się, jak włączyć WP_DEBUG, odczytać logi i krok po kroku namierzyć źródło kłopotów. Dzięki temu wiele usterek usuniesz samodzielnie, bez paniki i niepotrzebnych przestojów witryny.
Co daje tryb debugowania WordPress?
WordPress opiera się na PHP, a każdy motyw i wtyczka to po prostu kod. Gdy pojawia się błąd, skrypt często przestaje działać, a Ty widzisz biały ekran, komunikat o błędzie krytycznym albo sklep WooCommerce nie kończy procesu zamówienia. Tryb debugowania zamienia wtedy WordPress w „głośniejszy” system, który zaczyna raportować, co dokładnie poszło nie tak.
W trybie debugowania możesz zobaczyć błędy PHP, ostrzeżenia, informacje o przestarzałych funkcjach, a także zapisać je do pliku. To szczególnie ważne przy błędach, które pojawiają się tylko czasami, np. przy imporcie produktów czy generowaniu faktur. Log pozwala wtedy prześledzić całą sytuację krok po kroku.
Jak działa WP_DEBUG?
Za debugowanie WordPress odpowiada stała WP_DEBUG w pliku wp-config.php. Domyślnie ma wartość false, więc błędy nie są ani pokazywane, ani zapisywane. Dopiero gdy zmienisz ją na true, WordPress zaczyna wyświetlać informacje z interpretatora PHP, a w połączeniu z dodatkowymi stałymi może też tworzyć dziennik błędów.
Jeśli ustawisz jednocześnie WP_DEBUG_LOG i WP_DEBUG_DISPLAY, decydujesz, czy błędy zobaczy użytkownik na ekranie, czy trafią tylko do pliku debug.log. To idealne rozwiązanie na środowisku produkcyjnym – błędy zapisują się w tle, ale nie psują wizerunku strony w oczach klientów.
Czego nie robić przy debugowaniu?
Bardzo częsty błąd to pozostawienie trybu debugowania włączonego na stałe. Plik debug.log zaczyna wtedy rosnąć z każdym ostrzeżeniem. Przy większym ruchu w serwisie potrafi zajmować dziesiątki megabajtów i obciążać dysk oraz procesor przy każdym dopisie do pliku.
Zdarza się też, że ktoś zostawia na produkcji wyświetlanie błędów na stronie. Użytkownik widzi wtedy surowe komunikaty PHP, a w skrajnym przypadku także ścieżki do plików czy fragmenty konfiguracji. To nie tylko psuje odbiór witryny, ale też obniża bezpieczeństwo.
Jak włączyć tryb debugowania w WordPress?
Podstawowy sposób uruchomienia debugowania to edycja pliku wp-config.php. Ten plik leży w katalogu głównym instalacji WordPress, najczęściej w folderze public_html lub w katalogu domeny na serwerze.
Po połączeniu z serwerem przez FTP (np. FileZilla) lub przez menedżera plików w panelu hostingu otwierasz wp-config.php w edytorze i szukasz linii z WP_DEBUG. Jeśli jej nie ma, możesz ją dopisać poniżej komentarza „That’s all, stop editing!” lub obok innych stałych konfiguracyjnych.
Podstawowa konfiguracja WP_DEBUG
Najczęściej używany zestaw ustawień debugowania wygląda tak:
define( 'WP_DEBUG’, true );
define( 'WP_DEBUG_LOG’, true );
define( 'WP_DEBUG_DISPLAY’, false );
Ta konfiguracja sprawia, że WordPress zapisuje wszystkie błędy i ostrzeżenia do pliku wp-content/debug.log, ale nie pokazuje ich na stronie. Dzięki temu możesz spokojnie testować, odtwarzać błąd, a użytkownicy w tym czasie widzą normalnie działającą witrynę.
Gdy skończysz analizę, zmieniasz wartości z true na false albo całkowicie usuwasz te linijki. Wiele firm hostingowych wyraźnie zaleca, aby WP_DEBUG i WP_DEBUG_LOG działały tylko przez czas diagnozy.
Włączanie debugowania z poziomu panelu hostingu
Część dostawców hostingu udostępnia opcję wyświetlania błędów PHP bezpośrednio w panelu administracyjnym. Proces wygląda wtedy inaczej niż przez FTP, ale efekt jest podobny – możesz włączyć raportowanie błędów dla wybranej domeny.
Zazwyczaj trzeba wybrać domenę, sprawdzić przypisaną wersję PHP, przejść do sekcji typu „PHP – ustawienia globalne” czy „Opcje PHP” i tam zaznaczyć opcję wyświetlania błędów. Następnie wracasz do menedżera plików, odszukujesz katalog domeny, otwierasz wp-config.php i ustawiasz WP_DEBUG na true. Po zapisaniu pliku Twoja strona zaczyna wyrzucać komunikaty PHP na ekran.
Jak zapisywać i odczytywać logi błędów?
Sam komunikat na ekranie bywa pomocny, ale przy powtarzalnych lub trudnych błędach znacznie wygodniej pracuje się z logami. WordPress, WooCommerce i sam PHP potrafią zapisywać błędy w różnych miejscach – warto wiedzieć, gdzie ich szukać.
Podstawowy plik WordPress to wp-content/debug.log. Do tego dochodzą logi WooCommerce oraz globalne logi PHP, ustawiane w php.ini. Czasem hosting udostępnia jeszcze osobny plik „error_log” w katalogu domeny lub w panelu serwera.
debug.log WordPress
Gdy masz ustawiony WP_DEBUG_LOG na true, każdy błąd zapisuje się do pliku debug.log. Znajdziesz go w katalogu wp-content na serwerze. Możesz go pobrać przez FTP albo podglądnąć w menedżerze plików. W logu zobaczysz datę, godzinę, typ komunikatu i dokładny plik oraz linię, w której wystąpił problem.
Jeśli log zrobił się bardzo duży, pobierz go lokalnie, a na serwerze usuń lub zmień nazwę. WordPress sam utworzy nowy plik przy kolejnym błędzie. To prosty sposób na uporządkowanie starych wpisów i szybszą analizę aktualnych problemów.
Logi WooCommerce
WooCommerce ma własny mechanizm zapisywania błędów krytycznych. W panelu admina przejdź do WooCommerce → Status → Logi. Z rozwijanej listy wybierz plik zaczynający się od słowa fatal-errors i daty. W środku znajdziesz komunikaty o awariach, które dotyczyły zamówień, płatności czy integracji z zewnętrznymi usługami.
Te logi przydają się szczególnie wtedy, gdy sklep „gubi” zamówienia, nie generuje faktur lub nie kończy procesu płatności. Możesz wtedy odtworzyć sytuację, a następnie odczytać wpisy z dokładnego momentu wystąpienia błędu i przekazać je np. twórcy wtyczki.
Globalne logi PHP
Czasem błąd pojawia się jeszcze zanim WordPress zdąży uruchomić własny tryb debugowania. W takiej sytuacji pomocne są globalne logi PHP. Można je włączyć w pliku php.ini, dopisując linie:
ini_set(„log_errors”, 1);
ini_set(„error_log”, „/tmp/php-error.log”);
Po zapisaniu zmian interpretator PHP zaczyna tworzyć plik php-error.log w katalogu /tmp. Nie każdy hosting pozwala jednak na edycję php.ini. Wtedy najlepiej sprawdzić dokumentację serwera albo poprosić administrację o udostępnienie logów błędów PHP.
W wielu panelach hostingowych znajdziesz też zakładkę z logami, które możesz pobrać jednym kliknięciem. To szybki sposób na sprawdzenie, czy błędy nie wynikają z ograniczeń serwera, np. konfiguracji pamięci lub czasu wykonywania skryptów.
Jak diagnozować typowe błędy w WordPress?
Gdy masz już włączone debugowanie i dostęp do logów, możesz przejść do właściwej diagnozy. Najwięcej problemów w praktyce powodują konflikty wtyczek, motywów oraz ograniczenia środowiska PHP.
Rzadko kiedy problem znika sam. Warto więc krok po kroku odtwarzać sytuację, która go wywołała, sprawdzać wpisy w debug.log i po kolei wyłączać podejrzane elementy – wtyczki, motywy, niestandardowe fragmenty kodu.
Biały ekran po zalogowaniu do panelu
Biały ekran, czyli tzw. „white screen of death”, to częsty efekt poważnego błędu PHP. Po zalogowaniu zamiast kokpitu widzisz puste tło i nic więcej. Zwykle odpowiada za to niekompatybilna wtyczka lub motyw.
Jeżeli tuż przed wystąpieniem problemu instalowałeś nową wtyczkę, aktualizowałeś motyw lub wprowadzałeś zmiany w kodzie, cofnij te działania. Gdy nie masz już dostępu do panelu, połącz się z serwerem przez FTP i w katalogu wp-content/plugins zmień nazwę podejrzanego folderu, np. contact-form-7 na contact-form-7_old. Spowoduje to automatyczne wyłączenie wtyczki.
Jak wyłapać konflikt wtyczek?
Co robić, gdy nie wiesz, która wtyczka psuje stronę? Wtedy najlepiej zastosować metodę eliminacji. Najpierw sprawdź debug.log i zobacz, czy nazwa konkretnej wtyczki nie pojawia się w ścieżce do pliku. Jeśli tak, zacznij od niej. Gdy log nie wskazuje jasno winowajcy, możesz wyłączać wtyczki po kolei, zmieniając nazwy ich katalogów.
Kiedy po zmianie nazwy jednego z folderów strona nagle wróci do życia, masz już trop. Przywróć poprawne nazwy pozostałych wtyczek i sprawdzaj, przy której dokładnie zaczyna się problem. To prosta, ale bardzo skuteczna metoda diagnozy konfliktów.
Przekroczony maksymalny czas wykonania skryptu
Komunikat „Błąd krytyczny: Przekroczono maksymalny czas wykonania” oznacza, że skrypt PHP działał zbyt długo i serwer go przerwał. Taka sytuacja często pojawia się przy imporcie dużej liczby produktów do WooCommerce lub przy masowych operacjach na danych.
Aby temu zaradzić, trzeba zwiększyć wartość max_execution_time. Na wielu serwerach wystarczy dodać do pliku .htaccess w katalogu domeny wpis: php_value max_execution_time 300. Oznacza to 300 sekund na wykonanie skryptu. Jeżeli zmiana nie przyniesie efektu, możesz spróbować ustawić parametr w panelu hostingu albo skontaktować się z działem technicznym.
Jak przyspieszyć diagnozę i znaleźć źródło spowolnień?
Błędy to jedno, ale równie uciążliwa jest wolno działająca strona. Czasem debug.log świeci pustkami, a WordPress wczytuje się kilka sekund. W takich przypadkach przydają się narzędzia, które mierzą czas ładowania zapytań do bazy, wtyczek i zasobów.
Jednym z najpopularniejszych dodatków tego typu jest Query Monitor. To wtyczka z oficjalnego repozytorium WordPress, która po instalacji pokazuje specjalny pasek w admin barze i szczegółowe raporty na temat wydajności strony.
Narzędzie Query Monitor
Po zainstalowaniu Query Monitor możesz zobaczyć, ile zapytań do bazy wykonuje dana podstrona, które wtyczki generują największe obciążenie, jakie błędy PHP pojawiają się w trakcie ładowania oraz jakie zasoby są dodawane do kolejki skryptów i stylów. To bardzo konkretna lista, a nie ogólne „strona działa wolno”.
Jeżeli raport pokazuje, że jedna wtyczka generuje znacznie więcej zapytań niż reszta, warto ją wyłączyć lub poszukać lżejszego zamiennika. Długi czas odpowiedzi bazy może z kolei sugerować, że trzeba poprawić konfigurację serwera lub zoptymalizować tabele – zwłaszcza przy rozbudowanych sklepach.
Gdy połączenie wiedzy z logów WP_DEBUG, logów WooCommerce, globalnych logów PHP i danych z Query Monitor zbiega się w jednym punkcie, masz bardzo mocny trop. To wtedy najłatwiej wyczyścić błąd i odzyskać stabilnie działającą stronę WordPress.
FAQ – najczęściej zadawane pytania
Do czego służy tryb debugowania WordPress (WP_DEBUG)?
Tryb debugowania zamienia WordPress w „głośniejszy” system, który zaczyna raportować, co dokładnie poszło nie tak. Umożliwia on zobaczenie błędów PHP, ostrzeżeń, informacji o przestarzałych funkcjach, a także zapisanie ich do pliku.
Jak aktywować tryb debugowania w WordPress?
Tryb debugowania aktywuje się poprzez edycję pliku wp-config.php, który znajduje się w katalogu głównym instalacji WordPress. Należy znaleźć linię z WP_DEBUG i zmienić jej wartość na true, np. define( 'WP_DEBUG’, true );. Czasem opcja ta jest dostępna również z poziomu panelu hostingu.
Jaka jest zalecana konfiguracja WP_DEBUG, aby błędy były logowane, ale niewidoczne dla użytkowników?
Zalecany zestaw ustawień to: define( 'WP_DEBUG’, true );, define( 'WP_DEBUG_LOG’, true ); oraz define( 'WP_DEBUG_DISPLAY’, false );. Ta konfiguracja sprawia, że WordPress zapisuje błędy do pliku wp-content/debug.log, ale nie wyświetla ich na stronie.
Gdzie WordPress i WooCommerce zapisują logi błędów?
WordPress zapisuje błędy do pliku wp-content/debug.log, gdy WP_DEBUG_LOG jest ustawione na true. WooCommerce posiada własny mechanizm i logi błędów krytycznych można znaleźć w panelu admina przechodząc do WooCommerce → Status → Logi, wybierając pliki zaczynające się od fatal-errors.
Czego nie powinno się robić podczas debugowania WordPressa, szczególnie na środowisku produkcyjnym?
Nie należy pozostawiać trybu debugowania włączonego na stałe, ponieważ plik debug.log może nadmiernie rosnąć i obciążać system. Nie powinno się także wyświetlać błędów na stronie produkcyjnej (czyli pozostawiać WP_DEBUG_DISPLAY na true), gdyż psuje to wizerunek witryny i obniża bezpieczeństwo, ujawniając surowe komunikaty PHP.
Jak zdiagnozować problem białego ekranu po zalogowaniu do panelu WordPress?
Biały ekran, znany jako „white screen of death”, jest często efektem poważnego błędu PHP, spowodowanego przez niekompatybilną wtyczkę lub motyw. Gdy nie masz dostępu do panelu, należy połączyć się z serwerem przez FTP i w katalogu wp-content/plugins zmienić nazwę podejrzanego folderu wtyczki, aby ją automatycznie wyłączyć.
Jakie narzędzie może pomóc w diagnozowaniu problemów z wydajnością strony, gdy debug.log nie wskazuje błędów?
W takich przypadkach pomocna jest wtyczka Query Monitor. Jest to narzędzie z oficjalnego repozytorium WordPress, które po instalacji pokazuje szczegółowe raporty na temat wydajności strony, takie jak liczba zapytań do bazy danych, obciążenie generowane przez wtyczki oraz błędy PHP podczas ładowania.
