Jak włączyć tryb debugowania w WordPressie i odczytać błędy?

Jak aktywować tryb debugowania w pliku wp-config.php?

Aby uruchomić tryb debugowania, dodaj trzy linie do pliku wp-config.php, powyżej komentarza /* To wszystko, zakończ edycję! */:

• define( 'WP_DEBUG', true ); – uruchamia mechanizm debugowania.

• define( 'WP_DEBUG_LOG', true ); – zapisuje błędy do pliku debug.log.

• define( 'WP_DEBUG_DISPLAY', false ); – ukrywa błędy przed odwiedzającymi stronę.

Plik wp-config.php leży w głównym katalogu instalacji WordPressa. Otworzysz go przez klienta FTP (np. FileZilla) lub menedżer plików w panelu hostingu. Edytuj go w czystym edytorze tekstu, nigdy w Wordzie, który dodaje niewidoczne znaki formatowania.

Zanim cokolwiek zmienisz, wykonaj kopię zapasową strony i bazy danych. Literówka w tym pliku potrafi położyć całą witrynę, a backup pozwala cofnąć się w minutę. Kluczowe jest ustawienie WP_DEBUG_DISPLAY na false – dzięki temu diagnozujesz błędy po cichu, a użytkownicy nie widzą technicznych komunikatów.

Co dokładnie robią stałe WP_DEBUG, WP_DEBUG_LOG i WP_DEBUG_DISPLAY?

Te trzy stałe działają niezależnie i każda odpowiada za inny element diagnostyki. WP_DEBUG to główny przełącznik – bez niego dwie pozostałe nic nie robią. WP_DEBUG_LOG decyduje o zapisie błędów WordPress do pliku, a WP_DEBUG_DISPLAY o pokazywaniu błędów na ekranie.

Stała	Za co odpowiada	Zalecana wartość na produkcji
WP_DEBUG	Włącza raportowanie błędów PHP w WordPressie	true tylko na czas diagnozy
WP_DEBUG_LOG	Zapisuje błędy do /wp-content/debug.log	true
WP_DEBUG_DISPLAY	Wyświetla błędy bezpośrednio na stronie	false

Dlaczego rozdzielenie zapisu od wyświetlania jest tak ważne? Bo błąd pokazany na żywej stronie ujawnia ścieżki serwera i strukturę plików, co ułatwia atak. Zapis do dziennika daje Ci te same informacje, ale tylko dla Ciebie. Na środowisku deweloperskim możesz włączyć WP_DEBUG_DISPLAY, bo wtedy błąd na ekranie przyspiesza pracę.

Rozszerzona konfiguracja debugowania: SCRIPT_DEBUG, SAVEQUERIES i własna ścieżka debug.log

Poza trzema podstawowymi stałymi WordPress udostępnia kilka dodatkowych, które przydają się w trudniejszych przypadkach. Według dokumentacji WordPress (Debugging in WordPress) najważniejsze z nich to SCRIPT_DEBUG, SAVEQUERIES oraz możliwość wskazania własnej ścieżki logu.

• define( 'SCRIPT_DEBUG', true ); – ładuje pełne, nieskompresowane wersje plików CSS i JS z jądra. Używaj, gdy debugujesz problem z blokami, edytorem lub skryptami motywu.

• define( 'SAVEQUERIES', true ); – zapisuje każde zapytanie do bazy danych. Pomaga wykryć wolne zapytania, ale obciąża stronę, więc wyłączaj je po analizie.

• define( 'WP_DEBUG_LOG', '/pełna/ścieżka/do/pliku.log' ); – kieruje dziennik poza domyślny katalog wp-content, np. poza folder publiczny.

Własna ścieżka logu ma konkretny sens praktyczny. Domyślny debug.log leży w katalogu dostępnym z przeglądarki, a plik z błędami to gotowa mapa Twojej instalacji dla atakującego. Przeniesienie go poza public_html eliminuje ten problem. Jeśli podejrzewasz, że to zapytania do bazy spowalniają witrynę, SAVEQUERIES wskaże winowajcę – o innych metodach piszę w przewodniku o tym, jak przyspieszyć stronę na WordPressie.

Gdzie znajdziesz logi błędów: plik debug.log i logi serwera (php.ini)?

Domyślny plik debug.log znajduje się w katalogu /wp-content/ i powstaje automatycznie w chwili zapisu pierwszego błędu. Pobierzesz go przez FTP lub otworzysz w menedżerze plików hostingu. To pierwsze miejsce, które sprawdzasz przy każdym problemie z WordPressem.

Warto znać drugie źródło – logi błędów PHP po stronie serwera. WordPress zapisuje własny dziennik, ale serwer prowadzi też plik error_log, często dostępny w panelu hostingu w sekcji „Logi błędów”. Konfigurację logowania na poziomie PHP ustawia się w pliku php.ini lub .user.ini, gdzie parametry log_errors i error_log wskazują, gdzie trafiają błędy.

Dlaczego czasem debug.log się nie pojawia? Zwykle z jednego z trzech powodów: WP_DEBUG_LOG jest ustawione na false, katalog wp-content nie ma praw zapisu, albo od włączenia trybu żaden błąd jeszcze nie wystąpił. Jeśli plik nie powstaje mimo poprawnej konfiguracji, sprawdź logi serwera – błąd mógł pojawić się zanim WordPress w ogóle się uruchomił.

Jak czytać i interpretować wpisy w debug.log (Notice, Warning, Deprecated, Fatal error)?

Każdy wpis w debug.log ma tę samą budowę: datę, typ błędu, opis oraz plik i numer linii, w której wystąpił. Właśnie ta końcówka ze ścieżką jest najważniejsza – mówi dokładnie, gdzie szukać przyczyny. Przykład: PHP Fatal error: Uncaught Error: Call to undefined function... in /wp-content/plugins/nazwa/plik.php:370.

Typy błędów różnią się wagą. Nie każdy wpis oznacza awarię – część to tylko ostrzeżenia, które warto poprawić, ale nie muszą zatrzymywać strony.

Typ wpisu	Co oznacza	Priorytet
Fatal error	Błąd krytyczny – zatrzymuje wykonywanie kodu, częsta przyczyna białej strony	Naprawiaj natychmiast
Parse error	Błąd składni, zwykle literówka w kodzie	Naprawiaj natychmiast
Warning	Ostrzeżenie – strona zwykle działa, ale coś jest nie tak	Sprawdź wkrótce
Deprecated	Użyto funkcji przestarzałej, którą usunie nowsza wersja PHP	Zaplanuj poprawkę
Notice	Drobna sugestia, kod działa poprawnie	Niski

Zacznij zawsze od wpisów Fatal error – to one wywalają stronę. Wiele komunikatów Deprecated pojawia się po zmianie wersji PHP; jeśli widzisz ich lawinę, przyczyną bywa zbyt świeży serwer i stary kod wtyczki. W takiej sytuacji pomaga świadome podejście do tego, jak bezpiecznie aktualizować PHP w WordPressie, zamiast wyłączania samych komunikatów.

Debugowanie przez wtyczki: Query Monitor, WP Debugging i Debug Log Manager

Jeśli nie chcesz edytować plików ręcznie, te same efekty osiągniesz wtyczką. To dobra droga dla osób, które nie czują się pewnie w FTP i wp-config.php. Trzy wtyczki pokrywają większość potrzeb.

Wtyczka	Do czego służy	Kiedy ją wybrać
WP Debugging	Włącza tryb debugowania bez ręcznej edycji plików	Gdy chcesz prostego przełącznika dla początkujących
Debug Log Manager	Podgląd i czyszczenie debug.log z panelu WordPress	Gdy nie chcesz pobierać logu przez FTP
Query Monitor	Analiza zapytań, hooków, wydajności i błędów na żywo	Gdy diagnozujesz wolne zapytania i konflikty

Query Monitor to narzędzie o innej klasie niż pozostałe. Pokazuje w pasku administratora liczbę zapytań do bazy, czas ich wykonania i które wtyczki je generują. To najszybszy sposób, by zobaczyć, co realnie dzieje się pod maską strony. Zestawienie sprawdzonych narzędzi znajdziesz też w artykule o najlepszych wtyczkach WordPress.

Wtyczka czy ręczna edycja wp-config.php – którą metodę debugowania wybrać?

Odpowiedź brzmi: to zależy od tego, czy masz dostęp do panelu WordPress. Jeśli strona się loguje i działa, wtyczka jest wygodniejsza. Jeśli widzisz białą stronę i nie wchodzisz do panelu, zostaje tylko ręczna edycja wp-config.php przez FTP.

• Wybierz wtyczkę, gdy masz dostęp do wp-admin, nie znasz FTP i chcesz szybko podejrzeć log bez pobierania plików.

• Wybierz ręczną edycję, gdy panel jest niedostępny, gdy debugujesz problem uniemożliwiający logowanie lub gdy potrzebujesz stałych zaawansowanych, jak SCRIPT_DEBUG.

Jest jeszcze jeden powód, dla którego warto znać metodę ręczną. Wtyczka to dodatkowy kod, który sam może być źródłem konfliktu. Gdy diagnozujesz poważny błąd, im mniej zmiennych, tym lepiej – czysta edycja wp-config.php nie dokłada nowych elementów do układanki.

Co zrobić, gdy nie masz dostępu do wp-config.php na hostingu zarządzanym?

Na części hostingów zarządzanych plik wp-config.php jest zablokowany lub nadpisywany przez system. W takim przypadku masz trzy wyjścia: przełącznik debugowania w panelu hostingu, wtyczkę do debugowania albo kontakt z pomocą techniczną dostawcy.

Wielu dostawców hostingu WordPress udostępnia własny podgląd logów błędów w panelu, bez potrzeby dotykania plików. Szukaj sekcji „Logi”, „Error logs” lub „WordPress debug”. Jeśli jej nie ma, wtyczka typu WP Debugging włączy tryb debugowania z poziomu panelu administracyjnego WordPress, o ile masz do niego dostęp.

Dlaczego niektóre hostingi blokują ten plik? Bo zawiera dane dostępowe do bazy i klucze zabezpieczeń. Blokada chroni przed przypadkową zmianą, która położyłaby stronę. To ograniczenie, ale w praktyce zwiększa bezpieczeństwo – a log błędów i tak jest dostępny inną drogą.

Jak namierzyć wtyczkę lub motyw wywołujący białą stronę i błąd krytyczny?

Najszybsza droga to odczytać ścieżkę z debug.log – wpis Fatal error niemal zawsze wskazuje konkretny plik w folderze plugins lub themes. Jeśli logu nie ma, działasz metodą eliminacji: dezaktywujesz wszystkie wtyczki i sprawdzasz, czy błąd znika.

Przy braku dostępu do panelu robisz to przez FTP. Zmieniasz nazwę folderu wp-content/plugins na inną – WordPress dezaktywuje wtedy wszystkie wtyczki naraz. Gdy strona wraca, przywracasz nazwę i włączasz wtyczki pojedynczo, aż błąd wróci. Winowajca to ta ostatnia. Podobnie z motywem: przełączenie na domyślny (np. Twenty Twenty-Four) wyklucza problem po stronie szablonu.

Pamiętaj jednak, że nie każda przyczyna leży w plikach. Czasem błąd zostaje zapisany w bazie danych i sam plik wtyczki jest już poprawny.

Historia z doświadczenia: W jednym sklepie po aktualizacji wtyczki od płatności pojawił się błąd krytyczny na stronie zamówienia. Pliki były już zaktualizowane, ale w bazie danych została stara opcja z poprzedniej wersji, która wywalała stronę koszyka. Rozwiązaniem było wejście do bazy i zmiana tego parametru z ON na OFF – błąd zniknął od razu. To nie był kosmetyczny problem: według średniej sprzedaży z analityki sklepu każdy dzień z niedziałającym zamówieniem oznaczał około 600-1000 zł straty. Wkrótce autor wtyczki wydał nakładkę aktualizacji, która naprawiała to automatycznie, ale zamówień z tych godzin nikt by nie odzyskał. Dlatego ważne jest szczególnie w przypadku sklepów, weryfikację procesu zamówienia po każdej aktualizacji wtyczek.

Wniosek praktyczny: po każdej aktualizacji wtyczki płatności sprawdzaj proces zamówienia od razu, a nie po tygodniu. Jeśli błąd krytyczny dotyczy sklepu i tracisz sprzedaż z każdą godziną, warto zlecić naprawę strony internetowej specjaliście, zamiast eksperymentować na żywym systemie.

Kiedy warto włączać tryb debugowania, a nie tylko podczas awarii?

Tryb debugowania to nie tylko narzędzie ratunkowe – to również profilaktyka. Warto uruchamiać go po każdej większej zmianie: aktualizacji WordPressa, wtyczek, motywu czy wersji PHP. Wtedy wyłapujesz ostrzeżenia, zanim zamienią się w błąd krytyczny widoczny dla klientów.

Dobre momenty na włączenie diagnostyki to również praca na środowisku testowym, wdrażanie nowych funkcji i przenoszenie strony między serwerami. Na kopii roboczej możesz włączyć nawet wyświetlanie błędów na ekranie, bo nikt postronny jej nie widzi.

Dlaczego proaktywne podejście się opłaca? Bo komunikaty Deprecated i Warning to sygnał ostrzegawczy. Funkcja oznaczona jako przestarzała dziś, w kolejnej wersji PHP przestanie istnieć i wywoła awarię. Regularny przegląd logów po aktualizacji WordPressa pozwala naprawić problem w spokoju, a nie pod presją niedziałającego sklepu.

Jak bezpiecznie wyłączyć tryb debugowania i usunąć plik logów?

Po zakończeniu diagnozy wyłącz tryb debugowania, zmieniając wartości w wp-config.php z true na false. Ustaw tak przynajmniej WP_DEBUG, a najlepiej wszystkie trzy stałe. Następnie usuń plik debug.log z katalogu wp-content.

Dlaczego to nie jest opcjonalne? Pozostawiony na produkcji tryb debugowania niesie trzy realne ryzyka:

• Bezpieczeństwo – plik debug.log ujawnia ścieżki serwera i strukturę instalacji, co ułatwia atak.

• Wydajność – ciągłe logowanie i rozrastający się plik obciążają serwer.

• Wizerunek – przy włączonym wyświetlaniu błędów odwiedzający widzą techniczne komunikaty zamiast treści.

Jeśli chcesz zachować logowanie w tle, ale bez ryzyka, zostaw WP_DEBUG_LOG włączone z własną ścieżką poza folderem publicznym i utrzymuj WP_DEBUG_DISPLAY na false. To rozsądny kompromis dla stron, które chcesz monitorować na bieżąco.

Najczęstsze błędy i mity przy debugowaniu WordPressa

Większość problemów przy debugowaniu nie wynika z samego mechanizmu, lecz z powtarzalnych błędów użytkowników. Oto te, które najczęściej kończą się kłopotem:

• Pozostawienie WP_DEBUG_DISPLAY na true na produkcji – błędy widzą wszyscy odwiedzający, łącznie z danymi o konfiguracji.

• Brak kopii zapasowej przed edycją wp-config.php – jedna literówka potrafi zablokować całą stronę.

• Edycja pliku w Wordzie – procesor tekstu dodaje niewidoczne znaki, które psują kod. Używaj Notepad++ lub podobnego edytora.

• Zapomniany debug.log – plik rośnie miesiącami i staje się dziurą bezpieczeństwa.

• Wyłączanie komunikatów zamiast naprawy – ukrycie ostrzeżenia Deprecated nie usuwa problemu, tylko odsuwa go w czasie.

Najczęstszy mit? Że włączenie trybu debugowania może uszkodzić stronę. Sam tryb niczego nie psuje – jedynie zapisuje i pokazuje błędy, które już istnieją w kodzie. Ryzykowne jest tylko ustawienie WP_DEBUG_DISPLAY na true na żywej witrynie, bo ujawnia informacje publicznie. Debugowanie nie tworzy błędów. Ono je oświetla, żebyś mógł je naprawić, zanim zrobią to za Ciebie użytkownicy.