Debugowanie WordPress: Włączanie WP_DEBUG i czytanie logów błędów

Debugowanie WordPress: Włączanie WP_DEBUG i czytanie logów błędów

Zweryfikowano: lipiec 2026 – procedury sprawdzone pod WordPress 7.0.2 i nowoczesne stosy PHP 8.x.

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:

  1. Znajdź wp-config.php: Połącz się przez FTP, SFTP lub File Manager hosta. Przejdź do głównego katalogu instalacji WordPressa.
  2. Pobierz kopię zapasową: Przed edycją pobierz kopię wp-config.php na komputer. W razie problemów możesz ją ponownie wgrać.
  3. 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.
  4. 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. */.
  5. 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:

  1. Połącz się przez FTP lub File Manager: Użyj tej samej metody, co przy edycji wp-config.php.
  2. Przejdź do wp-content: Plik logu znajduje się w wp-content/debug.log.
  3. 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.
  4. 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.

Checklista wdrożenia debugowania WordPress

Praktyczne kroki, które pozwolą Ci bezpiecznie i skutecznie włączyć debugowanie w WordPressie oraz czytać logi błędów.

  1. Zrób pełną kopię zapasową strony, w tym plików i bazy danych, np. za pomocą pluginu UpdraftPlus lub narzędzi hostingu.
  2. Połącz się z serwerem przez FTP/SFTP lub użyj File Managera w panelu hostingu i pobierz plik wp-config.php z głównego katalogu WordPressa.
  3. Edytuj wp-config.php i dodaj lub zmodyfikuj stałe debugowania przed linią /* That's all, stop editing! */: define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false);
  4. Zapisz zmiany i prześlij zmodyfikowany plik wp-config.php z powrotem na serwer, nadpisując oryginał.
  5. Wywołaj błąd na stronie (np. odwiedzając stronę z problemem) aby wymusić zapis błędów do pliku wp-content/debug.log.
  6. Przejdź do folderu wp-content i pobierz plik debug.log, aby go przejrzeć. Skup się na błędach typu Fatal error i Warning z podaną ścieżką i numerem linii.
  7. Po zakończeniu debugowania wyłącz tryb debugowania, ustawiając w wp-config.php define('WP_DEBUG', false); i usuwając lub komentując pozostałe stałe debugowania.

Powiązane na WP-Dude

Jeśli interesujesz się debugowaniem WordPressa i chcesz lepiej zrozumieć, jak poprawić działanie swojej strony, warto również zapoznać się z innymi aspektami technicznymi i optymalizacyjnymi WordPressa.

Najczęstsze pytania (FAQ)

Oto najczęściej zadawane pytania dotyczące debugowania WordPress, które pomogą Ci efektywnie korzystać z WP_DEBUG i czytać logi błędów.

Jak włączyć WP_DEBUG w WordPress i co to daje?

Aby włączyć WP_DEBUG, edytuj plik wp-config.php i dodaj lub zmodyfikuj linię define('WP_DEBUG', true); przed /* That's all, stop editing! */. WP_DEBUG włącza tryb debugowania, który pozwala na wyświetlanie błędów PHP i ostrzeżeń, co ułatwia diagnozowanie problemów na stronie.

Gdzie znajduje się plik debug.log i jak go czytać?

Plik debug.log znajduje się w katalogu wp-content po włączeniu define('WP_DEBUG_LOG', true);. Zawiera szczegółowe informacje o błędach i ostrzeżeniach PHP. Czytaj go, szukając wpisów z datą i opisem błędu, co pozwala zidentyfikować źródło problemu.

Jakie stałe debugowania warto znać oprócz WP_DEBUG?

Poza WP_DEBUG warto używać WP_DEBUG_LOG (logowanie błędów do pliku), WP_DEBUG_DISPLAY (kontrola wyświetlania błędów na stronie) oraz SCRIPT_DEBUG (wymuszanie ładowania niezmienionych plików CSS/JS). Pozwala to na precyzyjne zarządzanie trybem debugowania.

Czy można używać wtyczek do debugowania zamiast ręcznego włączania WP_DEBUG?

Tak, wtyczki takie jak Query Monitor lub Debug Bar oferują wygodny interfejs do monitorowania błędów, zapytań do bazy i innych informacji. Są szczególnie przydatne dla użytkowników, którzy wolą unikać edycji plików systemowych.

Kiedy należy wyłączyć tryb debugowania w WordPress?

Tryb debugowania powinien być wyłączony na środowiskach produkcyjnych, aby nie ujawniać wrażliwych informacji użytkownikom i nie obciążać serwera. Wyłącz go, ustawiając define('WP_DEBUG', false); po zakończeniu diagnozy.

Jak interpretować najczęstsze komunikaty błędów w debug.log?

Typowe błędy to np. Fatal error (krytyczny problem zatrzymujący działanie), Warning (ostrzeżenia o potencjalnych problemach) i Notice (informacje o nieoptymalnym kodzie). Analiza tych wpisów pozwala szybko zlokalizować i naprawić błędy.

Loading (streaming)