Tryb debugowania WordPressa: jak włączyć WP_DEBUG i czytać debug.log

Tryb debugowania WordPressa włączasz, dodając do pliku wp-config.php stałą WP_DEBUG ustawioną na true. Na działającej stronie najlepiej połączyć ją z zapisem błędów do pliku (WP_DEBUG_LOG) i wyłączonym wyświetlaniem (WP_DEBUG_DISPLAY na false) — wtedy błędy PHP trafiają do wp-content/debug.log, a odwiedzający nic nie widzą.

Poniżej znajdziesz gotową konfigurację, opis wszystkich stałych debugowania, sposób czytania logu i rozwiązania najczęstszych sytuacji, np. białego ekranu czy komunikatu o błędzie krytycznym.

Co daje tryb debugowania WordPressa

Domyślnie WordPress ukrywa większość błędów PHP: ostrzeżenia, informacje o przestarzałych funkcjach (deprecated) i notice’y. To dobre dla odwiedzających, ale fatalne przy szukaniu przyczyny problemu — strona się psuje, a Ty nie wiesz dlaczego.

Po włączeniu WP_DEBUG WordPress raportuje wszystkie błędy PHP oraz własne komunikaty o użyciu przestarzałych funkcji, hooków i argumentów. Dzięki temu widzisz dokładnie, w którym pliku i w której linii coś poszło nie tak.

Jak włączyć tryb debugowania w wp-config.php

1. Połącz się z serwerem przez FTP/SFTP, menedżer plików w panelu hostingu lub SSH.
2. Zrób kopię pliku wp-config.php z głównego katalogu WordPressa.
3. Znajdź linię define( 'WP_DEBUG', false );. Jeśli jej nie ma, będziesz dodawać nowe linie.
4. Nad komentarzem /* That's all, stop editing! Happy publishing. */ wstaw konfigurację:

// Włącz raportowanie błędów
define( 'WP_DEBUG', true );

// Zapisuj błędy do pliku wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Nie wyświetlaj błędów na stronie
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

5. Zapisz plik i odtwórz problem (wejdź na stronę, która się psuje, wykonaj akcję w panelu).
6. Otwórz plik wp-content/debug.log.

Stałe muszą być zdefiniowane tylko raz. Jeśli w pliku jest już define( 'WP_DEBUG', false );, zmień wartość zamiast dodawać drugą linię — inaczej PHP zgłosi ostrzeżenie o ponownej definicji stałej.

Włączanie przez WP-CLI

Jeśli masz dostęp do SSH i WP-CLI, nie musisz ręcznie edytować pliku:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Parametr --raw sprawia, że wartość zostanie zapisana jako wartość logiczna true, a nie tekst 'true'.

Wszystkie stałe debugowania WordPressa

Zalecany zestaw na środowisko lokalne różni się od produkcyjnego: lokalnie możesz spokojnie ustawić WP_DEBUG_DISPLAY na true i włączyć SCRIPT_DEBUG, a na produkcji — tylko log do pliku.

Uwaga: Plik wp-content/debug.log jest domyślnie dostępny pod adresem twojadomena.pl/wp-content/debug.log. Może zawierać ścieżki serwera, fragmenty zapytań i dane z formularzy. Na stronie produkcyjnej zapisuj log poza katalogiem publicznym albo zablokuj do niego dostęp.

Bezpieczna lokalizacja pliku debug.log

Od WordPressa 5.1 w WP_DEBUG_LOG możesz podać pełną ścieżkę zamiast true. Najlepiej wybrać katalog powyżej public_html, do którego nie da się dojść z przeglądarki:

define( 'WP_DEBUG_LOG', '/home/uzytkownik/logs/wp-debug.log' );

Katalog musi istnieć i mieć prawa zapisu dla użytkownika, na którym działa PHP. Jeśli nie możesz wyjść poza katalog strony, zablokuj plik na serwerze. Apache 2.4 (w .htaccess):

<Files "debug.log">
  Require all denied
</Files>

Nginx (w konfiguracji serwera):

location ~* /debug\.log$ {
    deny all;
}

Jeśli po zmianach w .htaccess dostajesz błąd 403 na całej stronie, zobacz poradnik 403 Forbidden w WordPressie.

Jak czytać debug.log i znaleźć winowajcę

Typowy wpis wygląda tak:

[26-Sep-2026 09:14:02 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function przyklad_funkcja() in /home/uzytkownik/public_html/wp-content/plugins/jakas-wtyczka/includes/class-main.php:142

Co z niego wyczytasz:

• Typ błędu. Fatal error zatrzymuje wykonanie strony — to on odpowiada za biały ekran lub komunikat o błędzie krytycznym. Warning i Notice zwykle nie psują strony, ale wskazują na błąd w kodzie. Deprecated oznacza użycie funkcji, która zniknie w przyszłych wersjach PHP lub WordPressa.
• Ścieżkę pliku. Fragment /wp-content/plugins/jakas-wtyczka/ wskazuje wtyczkę, /wp-content/themes/ — motyw, /wp-includes/ lub /wp-admin/ — rdzeń (wtedy przyczyna często i tak leży we wtyczce, która przekazała złe dane; szukaj w stack trace poniżej).
• Numer linii. Przydaje się, gdy zgłaszasz błąd autorowi wtyczki.

Na serwerze z SSH log najwygodniej śledzić na żywo, odtwarzając w tym czasie problem w przeglądarce:

tail -f wp-content/debug.log

Najczęstsze scenariusze i co robić

Biały ekran lub „Na tej stronie wystąpił błąd krytyczny”

Od WordPressa 5.2 fatalne błędy PHP są przechwytywane: strona pokazuje komunikat o błędzie krytycznym, a na adres e-mail administratora trafia wiadomość z nazwą wtyczki lub motywu i linkiem do trybu odzyskiwania (recovery mode). Przez ten link zalogujesz się do panelu z wyłączonym problematycznym rozszerzeniem.

Jeśli e-mail nie dotarł (częste przy źle skonfigurowanej poczcie na hostingu), włącz debugowanie i sprawdź debug.log.

Brak dostępu do panelu — jak wyłączyć wtyczkę

• Przez FTP: zmień nazwę katalogu wtyczki w wp-content/plugins/ (np. dopisz -off). WordPress ją dezaktywuje. Jeśli nie wiesz, która to, zmień nazwę całego katalogu plugins i włączaj wtyczki po kolei.
• Przez WP-CLI:

wp plugin deactivate jakas-wtyczka
# lub wszystkie naraz
wp plugin deactivate --all

Motyw wyłączysz analogicznie — po zmianie nazwy katalogu aktywnego motywu WordPress przełączy się na domyślny, jeśli jest zainstalowany.

Błędy po aktualizacji PHP

Przejście na nowszą wersję PHP często ujawnia przestarzały kod we wtyczkach. W logu pojawiają się wtedy błędy Deprecated lub Fatal error z informacją o nieistniejącej funkcji. Rozwiązaniem jest aktualizacja wtyczki, zamiana na inną albo — tymczasowo — powrót do poprzedniej wersji PHP w panelu hostingu. Podstawy samego języka opisuje tekst PHP bez tajemnic.

Problemy z zadaniami w tle

Jeśli nie wysyłają się e-maile, nie publikują się zaplanowane wpisy albo nie działają kopie zapasowe, sprawdź log w czasie, gdy zadanie powinno się wykonać. Często przyczyną jest sam mechanizm WP-Cron — więcej w artykule WP-Cron vs Cron.

Logowanie błędów PHP poza WordPressem (.user.ini)

Stałe WordPressa działają dopiero po załadowaniu wp-config.php. Błędy, które pojawiają się wcześniej (np. błąd składni w samym wp-config.php), trafiają do logu serwera lub PHP. Na hostingach z PHP-FPM możesz ustawić logowanie w pliku .user.ini w katalogu strony:

log_errors = On
error_log = /home/uzytkownik/logs/php-errors.log
display_errors = Off
error_reporting = E_ALL

Na produkcji display_errors powinno być wyłączone. Zmiany w .user.ini nie działają natychmiast — PHP odczytuje ten plik ponownie domyślnie co 5 minut (user_ini.cache_ttl). Na serwerach z mod_php zamiast .user.ini używa się dyrektyw php_flag i php_value w .htaccess. Wiele paneli hostingowych udostępnia też podgląd logu błędów PHP bez grzebania w plikach.

Wskazówka: Do codziennej pracy nad stroną przydaje się wtyczka Query Monitor. Pokazuje błędy PHP, wolne zapytania do bazy, wywołania HTTP i hooki bezpośrednio w pasku administratora — tylko dla zalogowanych administratorów, więc nie trzeba włączać wyświetlania błędów dla wszystkich.

Jak wyłączyć tryb debugowania

Po zakończeniu diagnostyki przywróć bezpieczną konfigurację:

define( 'WP_DEBUG', false );

Usuń lub zakomentuj pozostałe stałe (WP_DEBUG_LOG, WP_DEBUG_DISPLAY, SCRIPT_DEBUG, SAVEQUERIES) i skasuj plik debug.log, który mógł urosnąć do setek megabajtów. Przy okazji warto przejrzeć inne ustawienia bezpieczeństwa panelu — np. czy ukrywanie adresu logowania ma sens, opisuje tekst Hide WP Admin — czy to zabezpieczy WordPressa.