Zgłoś problem

Jak diagnozować błędy PHP w WordPressie przy użyciu WP_DEBUG i logów serwera

Poradniki

Każdy, kto pracuje z WordPressem — niezależnie, czy jest to programista, administrator, czy właściciel strony — prędzej czy później spotka się z błędem PHP.
Niektóre są widoczne od razu (np. White Screen of Death), inne ukryte głęboko w logach serwera.

Aby skutecznie zdiagnozować i naprawić problem, warto poznać narzędzia, które oferuje sam WordPress: WP_DEBUG, WP_DEBUG_LOG i WP_DEBUG_DISPLAY, a także zrozumieć, jak korzystać z logów serwera.

W tym artykule pokażę Ci, jak włączyć debugowanie w WordPressie, gdzie szukać błędów i jak czytać logi PHP.

1. Co to jest WP_DEBUG?

WP_DEBUG to stała konfiguracyjna w WordPressie, która pozwala włączyć tryb debugowania.
Po jej aktywowaniu WordPress zaczyna wyświetlać lub zapisywać błędy PHP, ostrzeżenia i powiadomienia.

Domyślnie opcja ta jest wyłączona, ponieważ w środowisku produkcyjnym nie powinno się pokazywać błędów odwiedzającym stronę.

2. Jak włączyć WP_DEBUG

Otwórz plik wp-config.php (znajduje się w głównym katalogu WordPressa) i dodaj lub zmień poniższą linię:

define( 'WP_DEBUG', true );

Dzięki temu WordPress zacznie wykrywać błędy PHP i komunikaty systemowe.

💡 Wskazówka: jeśli pracujesz na stronie produkcyjnej, nie pokazuj błędów publicznie — zamiast tego zapisz je do logu (o tym niżej).

3. Zapis błędów do pliku – WP_DEBUG_LOG

Aby błędy były zapisywane do pliku, dodaj kolejną stałą:

define( 'WP_DEBUG_LOG', true );

Po jej włączeniu wszystkie błędy zostaną zapisane do pliku:

/wp-content/debug.log

Ten plik możesz otworzyć w dowolnym edytorze tekstowym lub podglądać w czasie rzeczywistym np. przez SSH:

tail -f wp-content/debug.log

🔒 Uwaga: upewnij się, że plik debug.log nie jest publicznie dostępny (np. przez .htaccess), aby nie ujawniać danych wrażliwych.

4. Ukrywanie błędów przed użytkownikami – WP_DEBUG_DISPLAY

W środowisku produkcyjnym warto błędy zapisywać, ale nie wyświetlać ich na stronie.
W tym celu dodaj:

define( 'WP_DEBUG_DISPLAY', false );

Dzięki temu błędy nadal będą zapisywane do pliku debug.log, ale nie pojawią się w przeglądarce.

Pełna, bezpieczna konfiguracja debugowania może wyglądać tak:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

5. Dodatkowe opcje debugowania

WordPress oferuje kilka dodatkowych stałych, które mogą Ci pomóc:

define( 'SCRIPT_DEBUG', true ); // wymusza ładowanie nie-zminifikowanych wersji JS i CSS
define( 'SAVEQUERIES', true ); // zapisuje zapytania SQL w $wpdb->queries (do analizy wydajności)

Opcja SAVEQUERIES może pomóc w diagnozowaniu problemów z bazą danych, ale nie należy jej używać w produkcji — znacząco spowalnia działanie strony.

6. Analiza błędów w debug.log

W pliku wp-content/debug.log znajdziesz wpisy podobne do tego:

[17-Oct-2025 10:22:11 UTC] PHP Warning:  Undefined variable $post_id in /wp-content/themes/motw/functions.php on line 42

Każdy wpis zawiera:

  • datę i godzinę błędu,
  • poziom błędu (Warning, Notice, Fatal error),
  • opis błędu,
  • ścieżkę do pliku i numer linii.

Najgroźniejsze są:

  • Fatal error – skrypt się zatrzymał, strona nie działa,
  • Parse error – błąd składniowy w kodzie PHP.

Warning i Notice zwykle nie zatrzymują działania strony, ale warto je naprawić — często prowadzą do większych błędów w przyszłości.

7. Gdzie znaleźć logi serwera

Nie wszystkie błędy trafiają do debug.log.
Wiele z nich zapisywanych jest w logach PHP na poziomie serwera.

W zależności od hostingu znajdziesz je w różnych lokalizacjach:

  • /var/log/apache2/error.log – dla Apache,
  • /var/log/nginx/error.log – dla Nginx,
  • w panelu hostingowym (np. DirectAdmin → Logi błędów lub Plesk → Dzienniki).

Jeśli korzystasz z LiteSpeed, logi znajdziesz zwykle w:

/usr/local/lsws/logs/error.log

8. Przykład diagnozy błędu krok po kroku

  1. Włącz WP_DEBUG i WP_DEBUG_LOG.
  2. Odśwież stronę, na której występuje błąd.
  3. Otwórz wp-content/debug.log.
  4. Znajdź wpis zawierający nazwę pliku i numer linii.
  5. Otwórz ten plik w edytorze i sprawdź kod w danym miejscu.
  6. Popraw błąd i przetestuj ponownie.

Przykład:

PHP Fatal error:  Uncaught Error: Call to undefined function get_user_date()

➡️ Oznacza to, że w kodzie wywołano funkcję, która nie istnieje (literówka lub brak pliku include).

9. Wskazówki bezpieczeństwa i dobre praktyki

  • Nigdy nie zostawiaj WP_DEBUG włączonego na produkcji.
  • Regularnie czyść plik debug.log, by nie zajmował zbyt dużo miejsca.
  • Jeśli korzystasz z systemu Git, dodaj debug.log do .gitignore.
  • Nie udostępniaj plików logów publicznie.
  • W środowisku staging możesz mieć WP_DEBUG włączony cały czas.

10. Podsumowanie

Diagnostyka błędów PHP w WordPressie to podstawowa umiejętność każdego administratora i dewelopera.
Dzięki WP_DEBUG i logom serwera możesz szybko wykrywać problemy, zanim zauważą je użytkownicy.

Włącz debugowanie tylko wtedy, gdy jest potrzebne, a po rozwiązaniu problemu — wyłącz je, by zachować bezpieczeństwo i wydajność strony.

Tag

KROK 1 Z 4

Z CZYM POTRZEBUJESZ POMOCY?