Debugowanie WordPress: Włączanie WP_DEBUG i czytanie logów błędów • WP-Dude.com

Dowiedz się, jak włączyć WP_DEBUG i czytać debug.log w WordPressie. Przewodnik krok po kroku do diagnozowania białych ekranów i błędów pluginów.

Table of Contents

Wprowadzenie

Dowiedz się, jak włączyć WP_DEBUG w WordPressie, czytać logi błędów i diagnozować problemy jak profesjonalista. Ten przewodnik zamieni Twój debug.log w potężne narzędzie do troubleshootingu.

Gdy strona WordPress pokazuje biały ekran, wyświetla niezrozumiałe błędy albo plugin nagle przestaje działać, musisz wiedzieć, co dzieje się pod maską. Pomyśl o debug.log jak o rejestratorze lotów dla Twojej strony WordPress—zapisuje, co się wydarzyło, gdy coś poszło nie tak. W tym artykule nauczysz się, jak włączyć WP_DEBUG, skonfigurować go bezpiecznie i interpretować generowane komunikaty. Dzięki temu samodzielnie znajdziesz przyczynę wielu typowych problemów z WordPressem.

Dlaczego debugowanie WordPress ma znaczenie

Narzędzia do debugowania dają Ci wgląd w to, co naprawdę się dzieje, gdy strona zachowuje się nietypowo—zamiast zgadywać, dostajesz konkretne odpowiedzi.

Strona WordPress bez włączonego debugowania to jak jazda z opaską na oczach: gdy coś się zepsuje, nie masz pojęcia dlaczego. Biały ekran? Konflikt pluginów? Przestarzała funkcja? Bez WP_DEBUG i debug.log zostaje Ci metoda prób i błędów—wyłączanie pluginów jeden po drugim w nadziei, że trafisz na winowajcę. Włączenie debugowania w WordPressie zmienia tę sytuację. Ujawnia błędy, ostrzeżenia i powiadomienia PHP, które wskazują bezpośrednio na plik, linię i przyczynę problemu. Niezależnie od tego, czy rozwiązujesz problem z 404, awarią pluginu czy konfliktem motywu—dostęp do logów błędów daje Ci kontrolę. To jedna z pierwszych umiejętności, które powinien opanować każdy poważny użytkownik lub developer WordPressa.

Zanim zaczniesz: bezpieczeństwo przede wszystkim

Zawsze przygotuj się przed edycją wp-config.php—kopia zapasowa i środowisko staging mogą uchronić Cię przed kosztownymi błędami.

Edycja wp-config.php to operacja niskiego ryzyka, jeśli robisz to poprawnie, ale to nadal kluczowy plik konfiguracyjny. Literówka lub źle wstawiony znak może wyłączyć stronę. Zanim włączysz WP_DEBUG, upewnij się, że masz podstawy:

Zrób kopię zapasową: Użyj pluginu takiego jak UpdraftPlus lub narzędzia do backupu od hosta. Uwzględnij pliki i bazę danych.
Korzystaj ze stagingu, jeśli to możliwe: Wiele hostów oferuje środowiska testowe. Najpierw przetestuj tam debugowanie, zwłaszcza na stronach produkcyjnych.
Miej dostęp przez FTP lub File Manager: Będziesz musiał edytować wp-config.php i ewentualnie pobrać debug.log. Upewnij się, że masz dostęp do plików strony.

Ważne: Nigdy nie włączaj WP_DEBUG na żywej stronie bez kopii zapasowej. Jeśli coś pójdzie nie tak podczas edycji, będziesz chciał szybko przywrócić działającą wersję strony.

Włączanie WP_DEBUG w wp-config.php

Dodanie kilku linii do wp-config.php wystarczy, by włączyć debugowanie w WordPressie i zacząć zapisywać błędy.

Plik wp-config.php znajduje się w głównym katalogu WordPressa—w tym samym folderze, co wp-admin, wp-content i wp-includes. Oto jak włączyć debugowanie krok po kroku:

Znajdź wp-config.php: Połącz się przez FTP, SFTP lub File Manager hosta. Przejdź do głównego katalogu instalacji WordPressa.
Pobierz kopię zapasową: Przed edycją pobierz kopię wp-config.php na komputer. W razie problemów możesz ją ponownie wgrać.
Otwórz plik w edytorze tekstu: Użyj zwykłego edytora (Notepad++, VS Code, Sublime Text). Unikaj Worda i edytorów formatowanego tekstu—mogą uszkodzić plik.
Znajdź linię: define( 'WP_DEBUG', false ); (lub podobną związaną z debugowaniem). Jeśli jej nie ma, szukaj linii /* That's all, stop editing! Happy blogging. */.
Dodaj poniższy kod przed tą linią:

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

Wyjaśnienie: Pierwsza linia włącza tryb debugowania. Druga kieruje wszystkie błędy do pliku logu zamiast na ekran. Trzecia i czwarta zapobiegają wyświetlaniu błędów na żywej stronie—odwiedzający nie zobaczą żadnych komunikatów. Błędy będą zapisywane tylko w wp-content/debug.log, który możesz przeglądać prywatnie.

Stałe debugowania w WordPressie

WordPress oferuje kilka stałych związanych z debugowaniem—znajomość działania każdej z nich pomoże Ci dopasować konfigurację do swojej sytuacji.

WP_DEBUG: Główny przełącznik. Gdy ustawione na true, WordPress raportuje błędy, ostrzeżenia i powiadomienia PHP. Wymagane do jakiegokolwiek debugowania.
WP_DEBUG_LOG: Gdy true, błędy są zapisywane do wp-content/debug.log. Niezbędne do przeglądania błędów bez wyświetlania ich na ekranie.
WP_DEBUG_DISPLAY: Gdy true, błędy pojawiają się w HTML stron. Na żywych stronach ustaw false—nie chcesz, by odwiedzający lub wyszukiwarki widziały wewnętrzne błędy.
SCRIPT_DEBUG: Ładuje niezmodyfikowane wersje plików JS i CSS WordPressa. Przydatne przy debugowaniu skryptów motywu lub pluginu. Dla większości użytkowników opcjonalne.
SAVEQUERIES: Zapisuje wszystkie zapytania do bazy w tablicy do analizy. Pomocne przy debugowaniu wydajności, ale dodaje obciążenie—używaj tylko na stagingu.

Tip: Na stagingu lub w środowisku deweloperskim użyj WP_DEBUG + WP_DEBUG_LOG + WP_DEBUG_DISPLAY ustawionego na false. Na żywych stronach, gdy musisz coś zdiagnozować, zastosuj to samo, ale pamiętaj, by wyłączyć debugowanie zaraz po zakończeniu.

WP_DEBUG – wyjaśnienie

WP_DEBUG to główna stała, która aktywuje zachowanie debugowania w WordPressie. Domyślnie PHP pokazuje tylko błędy krytyczne—te, które powodują biały ekran. Gdy ustawisz WP_DEBUG na true, WordPress raportuje także ostrzeżenia i powiadomienia. Są mniej poważne, ale często wskazują na przestarzałe funkcje, niezdefiniowane zmienne lub kod niezgodny z dobrymi praktykami. Wczesne ich wychwycenie pomaga uniknąć przyszłych awarii. Szczegóły znajdziesz w oficjalnej dokumentacji debugowania WordPressa.

WP_DEBUG_LOG i WP_DEBUG_DISPLAY

WP_DEBUG_LOG zapisuje błędy do pliku; WP_DEBUG_DISPLAY pokazuje je w przeglądarce. Na żywej stronie chcesz logowania, ale nie wyświetlania. Dlaczego? Błędy występujące podczas żądań AJAX, zadań crona czy akcji w panelu mogą nigdy nie pojawić się na stronie, którą oglądasz—trafiają tylko do logu. Gdy WP_DEBUG_DISPLAY jest true, błędy mogą też zepsuć układ strony, ujawnić ścieżki plików i wyglądać nieprofesjonalnie. Ustawienie WP_DEBUG_DISPLAY na false i poleganie na WP_DEBUG_LOG daje Ci potrzebne informacje bez tych wad.

Przykład: Wyobraź sobie formularz kontaktowy, który cicho zawodzi przy wysyłce. Błąd może wystąpić w obsłudze AJAX działającej w tle. Nie zobaczysz go na stronie—ale zostanie zapisany w debug.log. Dlatego logowanie jest niezbędne nawet przy wyłączonym wyświetlaniu.

SCRIPT_DEBUG i SAVEQUERIES (opcjonalnie)

SCRIPT_DEBUG wymusza ładowanie wersji deweloperskich plików JS i CSS WordPressa zamiast zminifikowanych. Przy debugowaniu konfliktu ze skryptami rdzenia WordPressa ułatwia to odczyt śladów stosu i odniesień do plików. SAVEQUERIES zapisuje każde zapytanie do bazy, które wykonuje WordPress, wraz z czasem wykonania. Nieocenione przy szukaniu wolnych zapytań, ale dodaje zauważalne obciążenie—strona będzie działać wolniej. Używaj tylko na stagingu lub lokalnie.

Czy wiesz, że: SAVEQUERIES może znacząco spowolnić stronę, bo rejestruje każde pojedyncze zapytanie do bazy. Włączaj tylko podczas aktywnego debugowania wydajności bazy i nigdy nie zostawiaj włączonego na produkcji.

Gdzie znaleźć i jak czytać debug.log

Gdy WP_DEBUG_LOG jest włączone, błędy trafiają do wp-content/debug.log—oto jak uzyskać do niego dostęp i go czytać.

Plik debug.log jest tworzony automatycznie w folderze wp-content przy pierwszym wystąpieniu błędu. Jeśli właśnie włączyłeś debugowanie i go jeszcze nie widzisz, wywołaj błąd (np. odwiedzając zepsutą stronę) i sprawdź ponownie. Aby uzyskać dostęp do pliku:

Połącz się przez FTP lub File Manager: Użyj tej samej metody, co przy edycji wp-config.php.
Przejdź do wp-content: Plik logu znajduje się w wp-content/debug.log.
Pobierz lub podejrzyj: Możesz pobrać plik i otworzyć w edytorze tekstu albo użyć File Managera hosta do podglądu. Niektórzy hostowie pokazują logi błędów też w panelu sterowania.
Czyść w razie potrzeby: Log rośnie z czasem. Dla świeżego startu podczas troubleshootingu możesz usunąć plik—WordPress utworzy nowy przy następnym błędzie.

Interpretacja częstych komunikatów błędów

Zrozumienie typów błędów w debug.log pomaga ustalić priorytety i szybko naprawiać problemy.

WordPress i PHP używają kilku standardowych poziomów błędów. Oto co zwykle zobaczysz:

Fatal error: Skrypt zatrzymuje się natychmiast. Często spowodowany brakującym plikiem, błędem składni lub wymaganą funkcją, która nie istnieje. Naprawiaj je w pierwszej kolejności.
Warning: Coś poszło nie tak, ale wykonanie trwa dalej. Może to być przestarzała funkcja, niezdefiniowana zmienna lub plik, którego nie udało się otworzyć. Ostrzeżenia często prowadzą do nieoczekiwanego zachowania.
Notice: Drobne problemy—niezdefiniowane indeksy, użycie przestarzałych funkcji. Mogą nie zepsuć strony, ale wskazują na kod wymagający aktualizacji.
Deprecated: Funkcja lub argument, który zostanie usunięty w przyszłej wersji WordPressa. Zaktualizuj motyw lub plugin, by używał zalecanej alternatywy.

Typowy wpis w logu wygląda tak: [04-Feb-2025 10:15:23 UTC] PHP Fatal error: Call to undefined function my_plugin_function() in /path/to/wp-content/plugins/my-plugin/my-plugin.php on line 42. Format podaje datę, typ błędu, komunikat, ścieżkę pliku i numer linii. Użyj tych informacji, by zlokalizować i naprawić problem. Pluginy takie jak Query Monitor i Debug Bar mogą też pokazywać błędy w pasku administracyjnym WordPressa, co ułatwia ich znalezienie bez otwierania pliku logu.

Pluginy debugujące jako alternatywa

Jeśli wolisz nie edytować wp-config.php albo chcesz wygodniejszego interfejsu, pomogą Ci pluginy do debugowania.

Debug Bar: Dodaje menu debugowania do paska administracyjnego. Gdy WP_DEBUG jest włączone, pokazuje ostrzeżenia i powiadomienia PHP w panelu. Świetne do szybkich sprawdzeń bez otwierania pliku logu.
Query Monitor: Pokazuje zapytania do bazy, żądania HTTP i błędy PHP w pasku administracyjnym. Bardziej rozbudowany niż Debug Bar—idealny dla developerów i zaawansowanych użytkowników.
WP Crontrol: Zarządza zadaniami crona WordPressa. Przydatny, gdy błędy występują podczas zadań zaplanowanych—możesz uruchomić je ręcznie i sprawdzić log.

Uwaga: Większość pluginów debugujących nadal wymaga włączenia WP_DEBUG w wp-config.php, by przechwytywać błędy. Dodają warstwę wygody na wbudowanym logowaniu.

Kiedy wyłączyć debugowanie

Debugowanie powinno być tymczasowe—gdy zidentyfikujesz i naprawisz problem, wyłącz je.

Trzymanie włączonego WP_DEBUG na żywej stronie ma wady. Może nieznacznie wpływać na wydajność, a jeśli WP_DEBUG_DISPLAY zostanie przypadkowo ustawione na true, wrażliwe informacje (ścieżki plików, dane bazy) mogą trafić do odwiedzających. Wyszukiwarki mogą też indeksować komunikaty błędów. Po rozwiązaniu problemu ustaw define( 'WP_DEBUG', false ); w wp-config.php i usuń lub zakomentuj pozostałe linie debugowania. Zachowaj kopię konfiguracji debugowania, jeśli spodziewasz się, że przyda się ponownie.

Ważne: Nigdy nie zostawiaj WP_DEBUG ustawionego na true na stronie produkcyjnej na dłużej. Używaj go do troubleshootingu, a potem wyłącz. Strona będzie działać sprawniej, a Ty unikniesz potencjalnych problemów z bezpieczeństwem i SEO.

FAQ

1. Czym jest WP_DEBUG i po co go używać?

Odpowiedź: WP_DEBUG to stała WordPressa, która po włączeniu sprawia, że PHP raportuje błędy, ostrzeżenia i powiadomienia. Używasz jej do diagnozowania problemów—białych ekranów, konfliktów pluginów, błędów motywu—widząc dokładnie, co poszło nie tak i gdzie. Jest niezbędna do troubleshootingu i rozwoju.

2. Czy bezpiecznie jest włączać WP_DEBUG na żywej stronie?

Odpowiedź: Tak, jeśli ustawisz WP_DEBUG_DISPLAY na false i WP_DEBUG_LOG na true. Błędy będą zapisywane tylko do pliku logu, nie pokazywane odwiedzającym. Mimo to używaj tego tymczasowo—włączaj przy troubleshootingu, napraw problem, potem wyłącz. Preferuj środowisko stagingowe, gdy to możliwe.

3. Gdzie znajduje się plik debug.log?

Odpowiedź: Plik debug.log jest tworzony w katalogu wp-content, pod ścieżką wp-content/debug.log. Pojawia się automatycznie po pierwszym błędzie po włączeniu WP_DEBUG_LOG. Dostęp przez FTP, SFTP lub File Manager hosta.

4. Jaka jest różnica między WP_DEBUG_LOG a WP_DEBUG_DISPLAY?

Odpowiedź: WP_DEBUG_LOG zapisuje błędy do pliku (debug.log); WP_DEBUG_DISPLAY pokazuje je w HTML stron. Na żywych stronach używaj WP_DEBUG_LOG i ustaw WP_DEBUG_DISPLAY na false, by odwiedzający nigdy nie widzieli komunikatów błędów. Przeglądaj log prywatnie.

5. Jak czytać i interpretować komunikaty błędów w debug.log?

Odpowiedź: Każda linia zwykle zawiera znacznik czasu, typ błędu (Fatal error, Warning, Notice), komunikat oraz plik i numer linii. Zacznij od ścieżki pliku i linii—tam leży źródło problemu. Błędy krytyczne zatrzymują wykonanie; ostrzeżenia i powiadomienia mogą powodować dziwne zachowanie. Najpierw napraw błędy krytyczne, potem zajmij się ostrzeżeniami.

6. Czy mogę użyć pluginu zamiast edytować wp-config.php?

Odpowiedź: Pluginy takie jak Debug Bar i Query Monitor dodają wygodniejszy interfejs do przeglądania błędów, ale zwykle nadal wymagają włączenia WP_DEBUG w wp-config.php. Nie da się w pełni włączyć debugowania w WordPressie bez edycji tego pliku. Pluginy go uzupełniają, nie zastępują.

7. Co zrobić, jeśli debug.log się nie pojawia?

Odpowiedź: Najpierw upewnij się, że WP_DEBUG i WP_DEBUG_LOG są ustawione na true. Potem wywołaj błąd—odwiedź stronę, o której wiesz, że powoduje problem, albo tymczasowo dodaj nieprawidłowy kod do pliku motywu. Log jest tworzony tylko przy wystąpieniu błędu. Sprawdź uprawnienia do wp-content—katalog musi być zapisywalny przez serwer WWW.

8. Kiedy wyłączyć WP_DEBUG?

Odpowiedź: Wyłącz zaraz po zakończeniu troubleshootingu. Nie ma potrzeby trzymać go włączonego po rozwiązaniu problemu. Na stronach produkcyjnych długotrwałe debugowanie może wpływać na wydajność i przy złej konfiguracji ujawnić wrażliwe dane. Wyłącz, gdy skończysz.

Podsumowanie

Włączaj WP_DEBUG bezpiecznie: Dodaj zalecane stałe do wp-config.php przed „That’s all, stop editing!”—zawsze używaj WP_DEBUG_LOG i ustaw WP_DEBUG_DISPLAY na false na żywych stronach.
Dostęp do debug.log: Plik znajduje się w wp-content/debug.log. Użyj FTP lub File Managera, by go pobrać i przeczytać.
Interpretuj błędy: Skup się najpierw na błędach krytycznych, potem na ostrzeżeniach i powiadomieniach. Użyj ścieżki pliku i numeru linii, by zlokalizować źródło.
Używaj pluginów jako wsparcia: Debug Bar i Query Monitor ułatwiają przeglądanie błędów, ale nadal wymagają WP_DEBUG w wp-config.php.
Wyłączaj po zakończeniu: Wyłącz WP_DEBUG po troubleshootingu, by uniknąć problemów z wydajnością i bezpieczeństwem.

Debugowanie WordPressa to potężna umiejętność—gdy wiesz, jak włączyć WP_DEBUG i czytać logi błędów, możesz diagnozować i naprawiać wiele problemów, które inaczej zostawiłyby Cię w martwym punkcie. Trzymaj ten przewodnik pod ręką, a wkrótce będziesz troubleshootować jak profesjonalista.