WP debug – jak włączyć tryb debugowania w WordPress?

Tryb WP_DEBUG w WordPress to wbudowany mechanizm do wykrywania i analizowania błędów na stronie, który włącza się poprzez edycję pliku wp-config.php i ustawienie stałej define('WP_DEBUG', true);. Dodatkowe stałe, takie jak WP_DEBUG_LOG i WP_DEBUG_DISPLAY, pozwalają kontrolować, czy błędy mają być zapisywane do pliku i czy mają się wyświetlać użytkownikom.

Co to jest tryb debugowania w WordPress?

WordPress posiada specjalny tryb debugowania sterowany stałą WP_DEBUG zdefiniowaną w pliku wp-config.php. Domyślnie w wielu instalacjach wartość tej stałej jest ustawiona na false, czyli tryb debugowania jest wyłączony.

Po ustawieniu:

define('WP_DEBUG', true);

WordPress zaczyna wyświetlać komunikaty o błędach, ostrzeżeniach i notice (powiadomieniach), które w normalnym trybie są zwykle ukryte.

Tryb debugowania jest szczególnie przydatny, gdy:

• strona wyświetla „białą stronę śmierci”,
• po aktualizacji motywu lub wtyczki coś przestało działać,
• pojawiają się przypadkowe błędy lub ostrzeżenia PHP.

Kiedy warto włączyć WP_DEBUG?

WP_DEBUG włącza się głównie wtedy, gdy trzeba znaleźć źródło problemu ze stroną.

Typowe sytuacje:

• aktualizacja WordPressa, motywu lub wtyczek powoduje błąd krytyczny na stronie,
• w panelu lub na froncie widzisz komunikat o błędzie PHP (Fatal error, Warning, Notice),
• chcesz sprawdzić, czy Twój własny kod (np. w motywie potomnym) nie generuje ostrzeżeń.

Po rozwiązaniu problemu wyłącz tryb debugowania, aby błędy nie były dalej wyświetlane ani logowane.

Jak przygotować się do włączenia debugowania?

Przed edycją pliku konfiguracyjnego warto zadbać o kilka rzeczy:

• dostęp do plików na serwerze – połącz się z serwerem przez klienta FTP (np. FileZilla) lub użyj menedżera plików w panelu hostingu;
• znalezienie pliku wp-config.php – plik wp-config.php znajduje się w głównym katalogu instalacji WordPressa (root strony);
• edytor tekstu – użyj prostego edytora tekstu (np. Notatnik, Notepad++, VS Code).

Przed wprowadzeniem zmian wykonaj kopię pliku wp-config.php.

Włączenie WP_DEBUG – wersja ręczna (krok po kroku)

Połączenie z serwerem

1. Połącz się z serwerem, na którym działa Twoja strona, za pomocą klienta FTP (np. FileZilla) albo menedżera plików w panelu hostingowym.
2. Przejdź do głównego katalogu WordPressa, gdzie znajdują się m.in. foldery wp-admin, wp-content, wp-includes.

Znalezienie i otwarcie pliku wp-config.php

1. W głównym katalogu znajdź plik wp-config.php.
2. Pobierz go na komputer albo otwórz bezpośrednio w edytorze tekstu przez menedżera plików.

Zmiana wartości WP_DEBUG

W większości instalacji znajdziesz linijkę:

define('WP_DEBUG', false);

Zmień wartość z false na true:

define('WP_DEBUG', true);

Po zapisaniu pliku i odświeżeniu strony tryb debugowania zostanie włączony.

Jeśli linijka z WP_DEBUG nie istnieje, możesz ją dodać samodzielnie.

WP_DEBUG_LOG i WP_DEBUG_DISPLAY – jak logować i ukrywać błędy?

Samo WP_DEBUG = true często nie wystarcza, szczególnie na stronie produkcyjnej. Warto użyć dodatkowych stałych:

Zapisywanie błędów do pliku – WP_DEBUG_LOG

Aby włączyć logowanie błędów do pliku, dodaj:

define('WP_DEBUG_LOG', true);

Ta stała powoduje, że błędy trafiają do logu (standardowo do pliku wp-content/debug.log).

Możesz ustawić własną ścieżkę pliku logu, np.:

define('WP_DEBUG_LOG', '/sciezka/do/pliku/wp-errors.log');

Wyświetlanie błędów w przeglądarce – WP_DEBUG_DISPLAY

Wyświetlanie komunikatów błędów użytkownikom możesz kontrolować stałą:

define('WP_DEBUG_DISPLAY', false);

Rekomendowana konfiguracja na produkcji (błędy nie wyświetlają się na stronie, ale są zapisywane do pliku):

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

Na środowisku testowym można włączyć również wyświetlanie błędów:

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

Dodatkowe stałe debugujące – SCRIPT_DEBUG i SAVEQUERIES

Możesz rozszerzyć możliwości debugowania za pomocą dodatkowych stałych:

define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);

SCRIPT_DEBUG – powoduje używanie niezminifikowanych wersji plików JS/CSS, co ułatwia szukanie błędów w skryptach.

SAVEQUERIES – zapisuje zapytania do bazy danych, co pozwala analizować ich wydajność i ewentualne błędy.

Takie ustawienia są szczególnie przydatne na środowisku developerskim lub testowym, a nie na stronie produkcyjnej.

Włączenie debugowania za pomocą wtyczki

Jeśli nie chcesz edytować pliku wp-config.php ręcznie, możesz skorzystać z wtyczki, np. WP Debugging.

Instalacja wtyczki

Kroki:

1. Zainstaluj i aktywuj wtyczkę WP Debugging z repozytorium wtyczek WordPress.
2. Po aktywacji wtyczka automatycznie ustawia odpowiednie stałe debugujące, m.in.:

   define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);

3. W panelu admina przejdź do sekcji Narzędzia » WP Debugging i upewnij się, że WP_DEBUG jest włączone.

Taka wtyczka ułatwia osobom nietechnicznym włączenie debugowania bez edycji plików konfiguracyjnych.

Jak sprawdzić, czy debugowanie działa?

Po zapisaniu zmian w wp-config.php lub włączeniu wtyczki wykonaj poniższe kroki weryfikacyjne:

• odśwież stronę, na której występował błąd,
• jeśli WP_DEBUG_DISPLAY jest ustawione na true, zobaczysz komunikaty błędów bezpośrednio w przeglądarce,
• jeśli używasz WP_DEBUG_LOG = true i masz wyłączone wyświetlanie, błędy będą zapisywane do pliku logu (np. debug.log).

Po zmianie konfiguracji ponownie wywołaj problematyczną stronę, tak by nowe błędy trafiły do logu i można je było przeanalizować.

Gdzie szukać pliku z logami błędów?

Domyślnie błędy są zapisywane do pliku wp-content/debug.log.

Jeśli ustawisz własną ścieżkę w WP_DEBUG_LOG, błędy trafią do wskazanego pliku, np.:

define('WP_DEBUG_LOG', '/sciezka/do/pliku/wp-errors.log');

Taka konfiguracja pozwala trzymać log w dowolnym miejscu (np. poza katalogiem publicznym).

Debugowanie WooCommerce z WP_DEBUG

Debugowanie WooCommerce opiera się na tych samych mechanizmach WordPressa – WP_DEBUG i WP_DEBUG_LOG. Po ich włączeniu błędy WooCommerce (np. płatności, integracje, szablony) trafią do logu tak jak komunikaty z WordPressa czy innych wtyczek.

Czytając plik debug.log, możesz identyfikować i odróżniać błędy związane z WooCommerce na podstawie ścieżek plików oraz nazw funkcji i klas.

Bezpieczeństwo – debugowanie na produkcji a na środowisku testowym

Po rozwiązaniu problemów wyłącz tryb debugowania, zmieniając true z powrotem na false.

Na stronie produkcyjnej nie zaleca się wyświetlania błędów użytkownikom (WP_DEBUG_DISPLAY powinno być false); natomiast wskazane jest logowanie błędów do pliku (WP_DEBUG_LOG = true), aby administrator mógł je przeanalizować bez ujawniania szczegółów osobom trzecim.

Na środowisku testowym lub developerskim możesz użyć bardziej szczegółowej konfiguracji, aby mieć maksymalną ilość informacji o błędach i działaniu strony:

define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', true);
define('WP_DEBUG_LOG', true);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);

Najczęstsze problemy przy włączaniu WP_DEBUG

Najczęstsze błędy to:

• błędna składnia w wp-config.php – pomyłki typu brak średnika, błędny cudzysłów czy przypadkowe usunięcie fragmentu kodu mogą spowodować błąd krytyczny;
• wpisanie stałych w złym miejscu w pliku – definicje stałych dodawaj w dolnej części wp-config.php, ale w obrębie znaczników PHP, a nie np. po zamknięciu ?>;
• pozostawienie WP_DEBUG włączonego na stałe – po rozwiązaniu problemu wyłącz debugowanie, zmieniając wartość z powrotem na false.

Przykładowe konfiguracje WP_DEBUG (do skopiowania)

Minimalna konfiguracja – szybkie wykrywanie błędów

define('WP_DEBUG', true);

Ta konfiguracja aktywuje debugowanie, ale nie loguje błędów do pliku ani nie kontroluje ich wyświetlania.

Bezpieczne debugowanie na produkcji (logowanie, bez wyświetlania)

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

Taki zestaw pozwala bezpiecznie zbierać informacje o błędach bez pokazywania ich użytkownikom.

Rozszerzone debugowanie na środowisku testowym

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);

To wygodna konfiguracja do diagnozowania problemów podczas prac developerskich.

Dobre praktyki pracy z WP_DEBUG

• zawsze rób kopię wp-config.php przed zmianami – aby móc szybko przywrócić poprzednią wersję;
• nie pozostawiaj WP_DEBUG włączonego na stałe na produkcji – po rozwiązaniu problemu zmień true na false;
• używaj WP_DEBUG_LOG – zamiast polegać wyłącznie na wyświetlaniu błędów, dzięki czemu masz historię błędów w pliku logu;
• rozważ użycie wtyczki WP Debugging – jeśli nie czujesz się pewnie w edycji plików;
• debuguj na środowisku testowym – szczególnie przy większych zmianach w motywie lub wtyczkach.

Takie podejście sprawia, że tryb debugowania jest skutecznym narzędziem diagnostycznym, a jednocześnie nie naraża użytkowników na oglądanie technicznych komunikatów błędów ani nie ujawnia wrażliwych szczegółów działania strony.