Jak włączyć WP_DEBUG w wp-config

Prawidłowo włączone logowanie błędów w WordPressie pozwala błyskawicznie namierzać konflikty wtyczek, motywów i niestandardowego kodu. Najważniejszym przełącznikiem jest WP_DEBUG, który uruchamia tryb diagnostyczny silnika, a po połączeniu z dodatkowymi stałymi zapewnia zarówno czytelne komunikaty, jak i bezpieczne logi do analizy. Poniższa instrukcja prowadzi krok po kroku: od przygotowania dostępu do plików, przez modyfikację konfiguracji, po praktykę czytania i porządkowania logów.

Co to jest WP_DEBUG i kiedy go włączać

Na czym polega debugowanie w WordPressie

Tryb debugowania w WordPressie to zestaw stałych konfiguracyjnych, które decydują o tym, czy błędy PHP, ostrzeżenia i uwagi deweloperskie są wyświetlane, rejestrowane do plików, a także czy wchodzą w życie dodatkowe mechanizmy przydatne przy diagnozowaniu problemów. Domyślnie WordPress nie eksponuje błędów użytkownikom, by nie odsłaniać wewnętrznych szczegółów aplikacji. Włączenie debugowania jest więc decyzją świadomą i najczęściej tymczasową, wykonywaną po to, by zebrać jak najwięcej informacji o przyczynie problemu.

Wpływ na widoczność błędów i zachowanie serwisu

Po aktywacji trybu debugowania mogą pojawić się komunikaty na froncie strony lub w panelu administracyjnym. Jeśli dodatkowo włączysz rejestrowanie do pliku, WordPress utworzy lub zacznie dopisywać do logu w katalogu wp-content. To cenne źródło informacji, ale wymaga rozwagi: nadmiar logów zwiększa rozmiar dysku, a błędy wyświetlane publicznie mogą ujawnić ścieżki plików czy fragmenty konfiguracji. Dlatego tak istotne jest rozdzielenie środowisk oraz bezpieczne ustawienia wyświetlania i logowania.

Kiedy używać, a kiedy nie

• Włączaj w trakcie diagnozy problemów: błędy 500, białe ekrany, nieoczekiwane zachowanie po aktualizacjach.
• Preferencyjnie używaj na środowiskach developerskich lub testowych, a w produkcji tylko krótkotrwale i bez publicznego pokazywania komunikatów.
• Wyłączaj po zakończeniu prac, porządkuj logi i monitoruj, czy problem nie wraca.

Plik konfiguracyjny WordPressa

Za konfigurację odpowiada plik wp-config.php w katalogu głównym instalacji. To tutaj znajdują się dane dostępowe do bazy, klucze bezpieczeństwa i stałe kontrolujące zachowanie WordPressa. Edycja wymaga ostrożności, bo błąd składni w tym pliku natychmiast unieruchomi witrynę. Pamiętaj, by każdą zmianę poprzedzić utworzeniem kopii pliku, a po edycji sprawdzić dzienniki serwera w razie krytycznego błędu.

Przygotowanie: dostęp do plików i bezpieczeństwo

Metody dostępu: hosting, menedżer plików, SSH

Najczęściej do plików WordPressa dostaniesz się poprzez panel hostingodawcy (menedżer plików), klienta FTP lub SFTP, a w środowiskach zaawansowanych – przez SSH. Najwygodniejsze do jednorazowej edycji bywa narzędzie w panelu hostingu, lecz w projektach długofalowych i automatyzacji najlepszą praktyką jest wersjonowanie konfiguracji (np. Git) i wdrażanie zmian przez proces CI/CD. Niezależnie od metody kluczowe jest zachowanie prawidłowych uprawnień plików i katalogów.

Odnalezienie właściwego pliku

Umiejscowienie pliku konfiguracyjnego zależy od struktury wdrożenia. Standardowo znajduje się on w katalogu głównym obok wp-admin, wp-content i wp-includes. W układach z repozytoriami lub niestandardowymi strukturami (np. Bedrock) plik z definicjami stałych może mieć inną lokalizację lub nazwę; sprawdź dokumentację projektu lub sekcję bootstrapu aplikacji, by trafić do właściwego miejsca definiowania stałych WordPressa.

Kopia bezpieczeństwa i kontrola wersji

Przed wprowadzeniem zmian przygotuj kopia zapasowa aktualnego pliku i – jeśli to możliwe – repozytorium Git, aby mieć historię modyfikacji. W środowiskach współdzielonych rób zmiany w krótkich oknach serwisowych i komunikuj je zespołowi. Zwróć uwagę na kodowanie pliku (UTF-8 bez BOM) i pilnuj, aby edytor nie wstawiał niewidocznych znaków na początku, bo to uniemożliwi wysyłkę nagłówków HTTP i może spowodować błędy sesji.

Uprawnienia i bezpieczeństwo transmisji

Jeżeli łączysz się do serwera, używaj bezpiecznego protokołu, preferując SFTP lub SSH. Unikaj zapisywania haseł w klientach FTP w formie jawnej. Ustaw uprawnienia plików (zazwyczaj 644) i katalogów (755), aby ograniczyć możliwość zapisu wyłącznie do tego, co konieczne. Po zakończeniu prac odśwież hasła do kont i sprawdź, czy dzienniki dostępu nie wykazują podejrzanych logowań.

Instrukcja: jak włączyć WP_DEBUG w wp-config.php

Minimalna i bezpieczna konfiguracja

Otwórz plik wp-config.php i odszukaj linię z komentarzem: To znaczy to wszystko, przestań edytować! Miłego blogowania. Zwyczajowo stałe debugowania umieszcza się tuż nad tą linią. Podstawowy, bezpieczny zestaw wygląda tak:

define(’WP_DEBUG’, true);

define(’WP_DEBUG_LOG’, true);

define(’WP_DEBUG_DISPLAY’, false);

@ini_set(’display_errors’, 0);

Pierwsza linia włącza debug, druga uruchamia logowanie do pliku, trzecia i czwarta blokują wyświetlanie błędów użytkownikom. Dzięki temu zbierasz informacje, ale nie ryzykujesz ujawniania szczegółów środowiska na froncie witryny.

Logowanie do pliku i jego lokalizacja

Domyślnie włączenie WP_DEBUG_LOG tworzy (lub uzupełnia) plik wp-content/debug.log. Jeżeli chcesz zapisywać log w innym katalogu, wskaż pełną ścieżkę:

define(’WP_DEBUG_LOG’, '/var/log/wordpress/debug.log’);

Pamiętaj, by katalog istniał i miał prawo zapisu dla użytkownika procesu PHP. Dobrym zwyczajem jest umieszczenie logów poza katalogiem publicznym serwera www lub zablokowanie bezpośredniego dostępu do nich regułami w .htaccess / nginx, aby nie były pobierane z zewnątrz.

Wyświetlanie komunikatów na ekranie

Stała WP_DEBUG_DISPLAY kontroluje, czy błędy będą renderowane w przeglądarce. Na produkcji zachowaj ją ustawioną na false. W środowisku lokalnym, gdy pracujesz samodzielnie i nie grozi to ujawnieniem danych, możesz tymczasowo ustawić true, aby szybciej zauważać ostrzeżenia. Dodatkowo dyrektywa @ini_set(’display_errors’, 0) pomaga nadpisać ustawienia php.ini, jeśli hosting domyślnie wymusza pokazywanie błędów.

Dodatkowe stałe i scenariusze użycia

Dla diagnoz front-endu przydatne bywa włączenie SCRIPT_DEBUG, które każe WordPressowi ładować nie-minifikowane wersje plików JS i CSS dostarczanych przez rdzeń i część wtyczek. Przy analizie wydajności zapytań do bazy ustaw SAVEQUERIES na true, co spowoduje gromadzenie w globalnej tablicy $wpdb->queries listy zapytań z czasem wykonania i źródłem. Tych opcji nie zostawiaj włączonych na stałe w produkcji – wpływają na wydajność i bezpieczeństwo.

define(’SCRIPT_DEBUG’, true);

define(’SAVEQUERIES’, true);

Przykładowa sekcja konfiguracji

Poniżej kompletny przykład bezpiecznego wariantu dla serwisu publicznego, który ma jedynie rejestrować błędy bez ich wyświetlania:

• define(’WP_DEBUG’, true);
• define(’WP_DEBUG_LOG’, true);
• define(’WP_DEBUG_DISPLAY’, false);
• @ini_set(’display_errors’, 0);

Dla środowiska deweloperskiego możesz dodatkowo włączyć:

• define(’SCRIPT_DEBUG’, true);
• define(’SAVEQUERIES’, true);

Po zapisaniu pliku odśwież stronę i odtwórz problem, aby log zarejestrował wpisy związane z błędem.

Wyłączenie debugowania i porządkowanie plików

Po zakończeniu diagnostyki wróć do wp-config.php i ustaw:

• define(’WP_DEBUG’, false);
• define(’WP_DEBUG_LOG’, false);
• define(’WP_DEBUG_DISPLAY’, false);

Następnie zarchiwizuj lub usuń plik logu. Uwzględnij rotację logów na serwerze, aby uniknąć zapełnienia dysku. Jeśli debugowanie było włączone dłużej, sprawdź wykorzystanie przestrzeni oraz limity hostingu – duże logi potrafią doprowadzić do błędów zapisu i przerwać działanie wtyczek.

Diagnostyka i praktyka pracy z logami

Jak czytać i interpretować debug.log

Podstawowy plik debug.log zawiera wiersze z datą, poziomem komunikatu i treścią błędu. Typowe wpisy to Notice, Warning i Fatal error. Najgroźniejsze są krytyczne błędy zatrzymujące wykonanie PHP, ale ostrzeżenia również należy eliminować – często sygnalizują przyszłe problemy (np. użycie przestarzałych funkcji). Szukaj powtarzających się wpisów i zwracaj uwagę na ścieżki do plików oraz numery linii, które wskażą, gdzie rozpocząć poprawki.

Wyszukiwanie wzorców i ograniczanie szumu

Przy obszernych logach łatwo utonąć w nadmiarze informacji. Skup się na:

• Czasie wystąpienia problemu – odfiltruj wpisy spoza tego okna.
• Sygnaturach błędów – powtarzające się ostrzeżenia wskazują na konkretną wtyczkę lub motyw.
• Poziomie powagi – Fatal > Warning > Notice.
• Nowościach po aktualizacjach – porównaj logi sprzed i po wdrożeniu.

Jeśli masz dostęp do shella, użyj narzędzi takich jak grep, less, awk, by wyciąć interesujące fragmenty. Na hostingu bez SSH możesz pobrać log i przeszukać lokalnie. Pamiętaj o anonimizacji danych przy udostępnianiu logów zespołowi lub dostawcy wsparcia.

Maskowanie wrażliwych danych i prywatność

Logi mogą zawierać fragmenty ścieżek systemowych, nazwy hostów, a czasem także dane z wyjątków i stack trace’ów. Zasady bezpiecznego udostępniania to m.in.: usuwanie tokenów, kluczy API i identyfikatorów użytkowników, ograniczenie zasięgu do niezbędnego fragmentu oraz czasowe, kontrolowane okno dostępu (np. link wygasający). Jeśli serwis przetwarza dane osobowe, wdróż politykę retencji logów i regularne czyszczenie zgodne z przepisami.

Narzędzia towarzyszące i współpraca z developerami

Poza natywnymi logami pomocne są: wtyczki profilerów zapytań SQL, inspektory hooków, monitory wydajności PHP oraz debug bary w panelu administracyjnym. W złożonych projektach włącz biblioteki do strukturalnego logowania (np. Monolog) integrowane z WordPressem i wysyłaj ważne zdarzenia do centralnych systemów (ELK/Opensearch, Sentry). Standaryzuj format logów i poziomy, aby zespół czytał je jednolicie.

Automatyzacja na różnych środowiskach

Dobra praktyka to różnicowanie konfiguracji w zależności od etapu pracy. Jeśli używasz zmiennej WP_ENVIRONMENT_TYPE, możesz warunkowo ustawiać debug:

if (defined(’WP_ENVIRONMENT_TYPE’) && WP_ENVIRONMENT_TYPE === 'development’) { define(’WP_DEBUG’, true); define(’WP_DEBUG_LOG’, true); define(’WP_DEBUG_DISPLAY’, true); } else { define(’WP_DEBUG’, false); define(’WP_DEBUG_LOG’, false); define(’WP_DEBUG_DISPLAY’, false); }

Takie podejście minimalizuje ryzyko przypadkowego pozostawienia włączonego debugowania po wdrożeniu. Dodatkowo trzymaj konfiguracje specyficzne dla serwerów w zmiennych środowiskowych (np. ścieżki do logów), by nie wpisywać w repo danych charakterystycznych dla jednej maszyny.

Najczęstsze problemy i rozwiązania

• Zdefiniowano stałe poniżej require_once ABSPATH . 'wp-settings.php’ – przenieś stałe debugowania nad tę linię, inaczej nie zadziałają odpowiednio wcześnie.
• Plik logu nie powstaje – sprawdź uprawnienia i właściciela katalogu docelowego, zweryfikuj open_basedir i disable_functions w konfiguracji PHP.
• Brak wpisów mimo błędów – upewnij się, że poziom błędów w PHP nie został ustawiony na 0 przez inne dyrektywy, i że błędy faktycznie występują (wywołaj sytuację testową).
• Komunikaty w przeglądarce mimo WP_DEBUG_DISPLAY=false – hosting może wymuszać display_errors; nadpisz to @ini_set(’display_errors’, 0) i/lub skontaktuj się z dostawcą.
• Ogromne logi i zapełnienie dysku – włącz rotację logów, przenieś je poza webroot, rozważ osobny wolumen na logi.

Bezpieczeństwo, wydajność i dobre praktyki

Oddzielenie ruchu użytkowników od diagnostyki

Aby nie wpływać na doświadczenie odwiedzających, diagnozuj błędy w oknach mniejszego ruchu i przygotuj plan szybkiego rollbacku zmian. W projektach komercyjnych używaj środowiska testowego staging, gdzie odwzorujesz konfigurację i dane na tyle, by wiarygodnie odtworzyć problem, ale bez ryzyka ujawnienia wrażliwych informacji publicznie.

Wydajność i koszt włączenia trybu debug

Rejestrowanie każdego ostrzeżenia to dodatkowe operacje wejścia/wyjścia i większe zużycie CPU. Najcięższe są funkcje zapisujące kompletne stack trace’y oraz stała SAVEQUERIES, która przechowuje wszystkie zapytania w pamięci. Plan działania: włączaj tylko to, co potrzebne; ograniczaj czas trwania diagnostyki; po zebraniu danych przechodź do analizy offline; po poprawkach testuj ponownie z wyłączonym debugiem, aby potwierdzić stabilność i odzyskaną wydajność.

Checklisty przed i po włączeniu debugowania

• Przed: wykonaj backup plików i bazy, przygotuj plan ewentualnego cofnięcia zmian, sprawdź uprawnienia i dostęp do serwera.
• W trakcie: wprowadzaj stałe w odpowiednim miejscu pliku, nie pokazuj błędów publicznie, rejestruj czas i kroki odtworzenia problemu.
• Po: wyłącz debug, posprzątaj logi, skontroluj miejsce na dysku i obciążenie, zaktualizuj dokumentację naprawy.

Najlepsze praktyki dla zespołów

Ustal wspólną konwencję definiowania stałych i miejsca ich deklaracji. Wersjonuj wp-config z wykorzystaniem plików lokalnych, które nie trafiają do repo (np. wp-config-local.php dołączany warunkowo). Dokumentuj decyzje diagnostyczne i wnioski z logów, aby kolejne osoby nie powielały pracy. Włącz monitorowanie stanu aplikacji (aplikacyjne health checki, alerty błędów), aby szybciej wyłapywać regresje po wdrożeniach.

Na koniec pamiętaj: odpowiednio ustawione WP_DEBUG, kontrolowane logowanie przez WP_DEBUG_LOG, niewyświetlanie komunikatów dzięki WP_DEBUG_DISPLAY, świadome użycie SCRIPT_DEBUG i SAVEQUERIES oraz praca na środowisku staging, z dostępem przez SFTP i aktualną kopia zapasowa, to fundament bezpiecznej i skutecznej diagnostyki WordPressa. Dzięki temu szybko wyłapiesz przyczyny błędów, nie narażając użytkowników na negatywne skutki ani ujawnianie poufnych informacji.