Jak tworzyć i uzyskiwać dostęp do dzienników błędów dla WordPress (3 metody)

Logi błędów WordPress to diagnostyczne zapisy, które rejestrują błędy PHP, wyjątki krytyczne, awarie bazy danych, konflikty wtyczek i niezgodności motywów w momencie ich wystąpienia na serwerze. Dostęp do tych logów i ich interpretacja to najszybszy sposób na zidentyfikowanie głównej przyczyny uszkodzonej strony, białego ekranu śmierci lub cichej regresji wydajności — bez zgadywania i wyłączania wtyczek jedna po drugiej.

Ten przewodnik omawia trzy przetestowane w środowisku produkcyjnym metody włączania, lokalizowania i odczytywania logów błędów WordPress: natywny stos WP_DEBUG, logi na poziomie serwera za pośrednictwem panelu sterowania hostingu oraz oparte na wtyczkach przeglądarki logów. Każda metoda jest odpowiednia dla innego poziomu dostępu i przypadku użycia, a wszystkie trzy są wyjaśnione z dokładnymi ścieżkami plików, składnią konfiguracji i kwestiami bezpieczeństwa.

Dlaczego logi błędów WordPress są ważne

WordPress działa na PHP, który generuje kilka klas komunikatów środowiska uruchomieniowego: błędy krytyczne (wykonanie zatrzymuje się), ostrzeżenia (wykonanie jest kontynuowane, ale coś jest nie tak), powiadomienia (informacyjne, często wskazujące na przestarzały kod) oraz komunikaty deprecated (funkcje zaplanowane do usunięcia). Domyślnie żaden z nich nie jest zapisywany do trwałego logu w większości konfiguracji produkcyjnych — są one albo tłumione, albo wyświetlane w przeglądarce, co stanowi zagrożenie bezpieczeństwa.

Bez logu aktualizacja wtyczki, która wprowadza błąd krytyczny, powoduje jedynie wyświetlenie pustego ekranu. Błędnie skonfigurowana biblioteka SMTP po cichu odrzuca wiadomości e-mail. Przekroczenie limitu pamięci powoduje awarię ładowania strony bez żadnego widocznego śladu. Logi błędów zamieniają te niewidoczne awarie w opatrzone znacznikiem czasu, z odniesieniem do pliku i numerem linii wpisy, na których możesz natychmiast działać.

Metoda 1: Włączanie trybu debugowania WordPress za pomocą wp-config.php

WordPress jest dostarczany z wbudowanym podsystemem debugowania kontrolowanym przez zestaw stałych PHP zdefiniowanych w wp-config.php. Jest to najdokładniejsza metoda, ponieważ przechwytuje błędy specyficzne dla WordPress, w tym te zgłaszane przez API wtyczek, moduł ładowania motywów i warstwę abstrakcji bazy danych (wpdb).

Krok 1: Zlokalizuj i otwórz wp-config.php

Połącz się z serwerem przez SFTP (preferowane zamiast zwykłego FTP ze względów bezpieczeństwa) za pomocą klienta takiego jak FileZilla lub Cyberduck, lub otwórz Menedżer plików swojego dostawcy hostingu. Przejdź do głównego katalogu WordPress, zazwyczaj /public_html/ lub /var/www/html/. Plik wp-config.php znajduje się w katalogu głównym tego katalogu.

Jeśli masz dostęp SSH, możesz edytować go bezpośrednio:

nano /var/www/html/wp-config.php

Krok 2: Skonfiguruj stałe debugowania

Zlokalizuj istniejącą linię:

define( 'WP_DEBUG', false );

Zastąp cały blok następującą konfiguracją, która włącza logowanie bez ujawniania błędów odwiedzającym witrynę:

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

Co robi każda stała:

• WP_DEBUG — aktywuje silnik debugowania WordPress i włącza raportowanie błędów PHP na poziomie E_ALL.
• WP_DEBUG_LOG — zapisuje wszystkie przechwycone błędy do pliku logu zamiast (lub dodatkowo) na ekranie.
• WP_DEBUG_DISPLAY — gdy ustawione na false, tłumi wyświetlanie na ekranie. Jest to kluczowe na stronach produkcyjnych; bez tego powiadomienia PHP ujawniają wewnętrzne ścieżki plików i nazwy zmiennych odwiedzającym.
• display_errors — podstawowa dyrektywa PHP; ustawienie jej na 0 za pomocą ini_set zapewnia drugą warstwę tłumienia na wypadek, gdyby wtyczka lub motyw nadpisały WP_DEBUG_DISPLAY.

Krok 3: Zlokalizuj plik logu debugowania

Gdy WP_DEBUG_LOG jest ustawione na true, WordPress zapisuje błędy do:

/wp-content/debug.log

Ten plik jest tworzony automatycznie przy pierwszym zarejestrowanym błędzie. Możesz go przeglądać przez SFTP lub SSH:

tail -f /var/www/html/wp-content/debug.log

Flaga tail -f strumieniuje nowe wpisy w czasie rzeczywistym, co jest nieocenione podczas interaktywnego odtwarzania konkretnego błędu.

Krok 4: Użyj niestandardowej ścieżki logu (zalecane ze względów bezpieczeństwa)

Domyślna ścieżka debug.log jest publicznie dostępna, jeśli serwer WWW nie blokuje jej jawnie. Błędnie skonfigurowany serwer będzie serwował https://yourdomain.com/wp-content/debug.log każdemu odwiedzającemu, ujawniając wewnętrzne ścieżki, prefiksy tabel bazy danych i nazwy klas.

Opcja A — Przenieś plik logu poza katalog główny serwera WWW:

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

Utwórz katalog docelowy i ustaw uprawnienia:

mkdir -p /var/log/wordpress
chown www-data:www-data /var/log/wordpress
chmod 750 /var/log/wordpress

Opcja B — Zablokuj domyślną ścieżkę przez .htaccess (Apache):

<Files "debug.log">
    Order allow,deny
    Deny from all
</Files>

Opcja C — Odpowiednik Nginx w bloku serwera:

location ~* /wp-content/debug.log {
    deny all;
    return 404;
}

Krok 5: Wyłącz tryb debugowania po rozwiązaniu problemu

Nigdy nie pozostawiaj WP_DEBUG ustawionego na true na działającej stronie dłużej niż to konieczne. Po rozwiązaniu problemu:

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

Pozostawienie aktywnego trybu debugowania na stronie produkcyjnej obniża wydajność (PHP przetwarza każde powiadomienie E_ALL) i może ujawniać wrażliwe ślady stosu, jeśli WP_DEBUG_DISPLAY zostanie przypadkowo ustawione na true.

Metoda 2: Dostęp do logów błędów na poziomie serwera za pośrednictwem panelu sterowania hostingu

Błędy WordPress, które występują przed zakończeniem uruchamiania WordPress — takie jak uszkodzony wp-config.php, niezgodność wersji PHP lub nieudane połączenie z bazą danych — nigdy nie pojawią się w debug.log, ponieważ sam WordPress nigdy się nie ładuje. W takich przypadkach potrzebny jest log błędów PHP serwera lub log błędów Apache/Nginx.

Hosting oparty na cPanel

Jeśli Twoje środowisko hostingowe używa VPS z cPanel, log błędów jest dostępny przez interfejs panelu sterowania:

1. Zaloguj się do cPanel.
2. Przejdź do Metryki > Błędy.
3. Panel wyświetla ostatnie 300 linii logu błędów Apache dla Twojego konta.

Aby uzyskać pełny plik logu, użyj Menedżera plików cPanel lub połącz się przez SFTP i przejdź do:

/home/yourusername/logs/yourdomain.com-ssl_log
/home/yourusername/logs/yourdomain.com-error_log

Dokładne nazwy plików różnią się w zależności od konfiguracji serwera, ale wzorzec jest spójny w większości instalacji cPanel.

Hosting oparty na Plesk

W Plesk przejdź do Witryny i domeny > wybierz swoją domenę > Logi. Możesz filtrować według typu logu (dostęp, błąd, PHP) i pobrać pełny plik logu.

Bezpośredni dostęp do serwera (VPS lub dedykowany)

W środowisku Hostingu VPS lub Serwera dedykowanego, gdzie masz dostęp root, lokalizacje logów zależą od Twojego stosu:

Aby monitorować log PHP-FPM w czasie rzeczywistym:

tail -f /var/log/php8.2-fpm.log

Aby wyszukać błędy krytyczne specyficzne dla WordPress w logu Apache:

grep -i "fatal|wordpress|wp-" /var/log/apache2/error.log | tail -50

Konfigurowanie logowania błędów PHP na poziomie serwera

Jeśli błędy PHP nie są zapisywane do logu, sprawdź konfigurację php.ini:

php --ini | grep "Loaded Configuration"

Otwórz zidentyfikowany plik php.ini i zweryfikuj lub ustaw:

log_errors = On
error_log = /var/log/php_errors.log
display_errors = Off
error_reporting = E_ALL

Uruchom ponownie PHP-FPM po wprowadzeniu zmian:

systemctl restart php8.2-fpm

Alternatywnie, nadpisz ustawienia PHP dla poszczególnych witryn za pomocą pliku .htaccess (tylko Apache):

php_flag log_errors on
php_value error_log /var/log/wordpress/php_errors.log
php_flag display_errors off

Metoda 3: Użyj wtyczki do logowania błędów WordPress

W środowiskach, gdzie bezpośredni dostęp do serwera jest ograniczony — takich jak Hosting współdzielony — lub dla zespołów, w których niespecjalistyczni administratorzy muszą przeglądać błędy bez dostępu SSH, wtyczka WordPress stanowi realną alternatywę.

Zalecane wtyczki

• WP Log Viewer — odczytuje istniejący plik debug.log i wyświetla go w panelu administracyjnym WordPress z filtrowaniem i wyszukiwaniem.
• Error Log Monitor — dodaje widget pulpitu nawigacyjnego pokazujący ostatnie błędy i może wysyłać alerty e-mail po zarejestrowaniu nowych błędów.
• Query Monitor — wykracza poza logowanie błędów, profilując zapytania do bazy danych, wywołania HTTP API, hooki i tagi warunkowe. Niezbędny do debugowania wydajności.
• Health Check & Troubleshooting — oficjalna wtyczka WordPress.org; włącza tryb rozwiązywania problemów, który aktywuje domyślny motyw i wyłącza wszystkie wtyczki tylko dla Twojej sesji, nie wpływając na innych odwiedzających.

Instalowanie i konfigurowanie Error Log Monitor

1. W panelu administracyjnym WordPress przejdź do Wtyczki > Dodaj nową.
2. Wyszukaj Error Log Monitor i kliknij Zainstaluj teraz, a następnie Aktywuj.
3. Przejdź do Ustawienia > Error Log Monitor.
4. Ustaw ścieżkę do pliku logu. Jeśli przeniosłeś debug.log poza katalog główny serwera WWW, wprowadź tutaj bezwzględną ścieżkę serwera.
5. Skonfiguruj częstotliwość alertów e-mail, jeśli chcesz otrzymywać powiadomienia o nowych typach błędów.

Wtyczka odczytuje ten sam plik debug.log, do którego zapisuje WP_DEBUG_LOG. Nie tworzy oddzielnego mechanizmu logowania — jest przeglądarką. Oznacza to, że WP_DEBUG i WP_DEBUG_LOG muszą być nadal włączone w wp-config.php, aby wtyczka mogła cokolwiek wyświetlić.

Krytyczne ograniczenie: Wtyczki ładują się po uruchomieniu WordPress. Każdy błąd, który uniemożliwia załadowanie WordPress (awaria połączenia z bazą danych, uszkodzony plik rdzenia, niezgodna wersja PHP) nie będzie widoczny w żadnej przeglądarce logów opartej na wtyczkach. W takich scenariuszach jedyną opcją jest Metoda 2.

Porównanie: trzy metody logowania błędów WordPress

Odczytywanie i interpretowanie wpisów logu błędów WordPress

Surowy wpis debug.log wygląda następująco:

[04-Jul-2025 14:32:11 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_field() in /var/www/html/wp-content/themes/mytheme/functions.php:47
Stack trace:
#0 /var/www/html/wp-content/themes/mytheme/functions.php(47): get_field()
#1 {main}
thrown in /var/www/html/wp-content/themes/mytheme/functions.php on line 47

Jak to odczytać:

• Znacznik czasu jest w UTC — w razie potrzeby przelicz na lokalną strefę czasową serwera.
• PHP Fatal error oznacza zatrzymanie wykonania. Strona, która wywołała ten błąd, zwróciła błąd 500 lub pusty ekran.
• Call to undefined function get_field() oznacza, że wtyczka Advanced Custom Fields jest albo dezaktywowana, albo załadowana po tym, jak functions.php motywu próbował ją wywołać.
• Ślad stosu pokazuje dokładny plik i numer linii. Rozpocznij debugowanie od linii 47 pliku functions.php.

Typowe wzorce błędów i ich przyczyny:

• PHP Warning: require(): Failed opening required — ścieżka do pliku jest nieprawidłowa lub plik nie istnieje. Często spowodowane przez wtyczkę odwołującą się do usuniętego pliku.
• PHP Deprecated: Function _register_controls is deprecated — wtyczka lub motyw używa przestarzałego API. Nie jest krytyczny, ale wskazuje na wtyczkę, która nie została zaktualizowana dla bieżącej wersji WordPress/Elementor.
• WordPress database error ... for query — zapytanie wpdb nie powiodło się. Sprawdź niezgodności prefiksów tabel lub uszkodzone tabele.
• Maximum execution time of 30 seconds exceeded — skrypt działał zbyt długo. Częste przy dużych importach, niezoptymalizowanych zapytaniach lub wywołaniach zewnętrznego API, które przekraczają limit czasu.
• Allowed memory size of X bytes exhausted — PHP osiągnął limit pamięci. Zwiększ memory_limit w php.ini lub zidentyfikuj wtyczkę powodującą wyciek pamięci.

Najlepsze praktyki zarządzania logami błędów WordPress

Rotuj logi, aby zapobiec wyczerpaniu miejsca na dysku. Zajęta witryna WordPress atakowana lub z powtarzającym się błędem może generować setki megabajtów danych logu dziennie. Na serwerach Linux skonfiguruj logrotate:

nano /etc/logrotate.d/wordpress-debug

/var/log/wordpress/debug.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    create 640 www-data www-data
}

Nigdy nie commituj debug.log do systemu kontroli wersji. Dodaj go do .gitignore:

wp-content/debug.log

Sprawdzaj wp-config.php po każdej migracji serwera. Migracje hostingu często resetują WP_DEBUG do false lub wprowadzają nowy szablon wp-config.php, który nadpisuje Twoje stałe.

Używaj SAVEQUERIES do debugowania na poziomie bazy danych. Dodaj tę stałą obok WP_DEBUG, aby rejestrować każde zapytanie SQL wykonywane przez WordPress:

define( 'SAVEQUERIES', true );

Następnie sprawdź $wpdb->queries w niestandardowym szablonie lub przez Query Monitor. Wyłącz go natychmiast po użyciu — przechowuje każde zapytanie w pamięci i znacznie zwiększa zużycie RAM.

Koreluj znaczniki czasu logów ze zdarzeniami wdrożeniowymi. Jeśli pojawi się nowy typ błędu, sprawdź, czy zbiega się z aktualizacją wtyczki, aktualizacją rdzenia WordPress lub zmianą wersji PHP na serwerze. Większość paneli sterowania hostingu rejestruje zmiany wersji PHP w oddzielnym dzienniku audytu.

Macierz decyzyjna: którą metodę wybrać

Techniczna lista kontrolna kluczowych wniosków

• Ustaw WP_DEBUG_DISPLAY na false przed włączeniem WP_DEBUG_LOG na jakiejkolwiek stronie z ruchem na żywo.
• Przenieś debug.log poza katalog główny serwera WWW lub zablokuj go przez reguły serwera — domyślna ścieżka jest publicznie dostępna.
• Używaj tail -f na pliku logu podczas interaktywnego odtwarzania błędów; eliminuje to potrzebę ręcznego odświeżania pliku.
• Logi PHP i Apache/Nginx na poziomie serwera są jedynym źródłem prawdy dla błędów, które występują przed załadowaniem WordPress.
• Przeglądarki logów oparte na wtyczkach wymagają aktywnego WP_DEBUG_LOG — są czytelnikami, nie autorami.
• Wdrożyj rotację logów na każdym serwerze, gdzie WP_DEBUG_LOG jest włączone przez więcej niż kilka godzin.
• Nigdy nie pozostawiaj SAVEQUERIES włączonego w środowisku produkcyjnym; jest to obciążenie dla pamięci i wydajności.
• Po rozwiązaniu problemu ustaw wszystkie stałe debugowania z powrotem na false i zweryfikuj za pomocą żądania przeglądarki, że w źródle strony nie pojawiają się żadne powiadomienia PHP.

—

Często zadawane pytania

Gdzie domyślnie znajduje się plik logu debugowania WordPress?

WordPress zapisuje log debugowania do /wp-content/debug.log względem głównego katalogu WordPress. Ta ścieżka jest tworzona dopiero po zarejestrowaniu pierwszego błędu i tylko gdy zarówno WP_DEBUG, jak i WP_DEBUG_LOG są ustawione na true w wp-config.php. Możesz nadpisać ścieżkę, podając bezwzględną ścieżkę do pliku jako wartość WP_DEBUG_LOG zamiast true.

Czy bezpieczne jest włączanie WP_DEBUG na działającej stronie produkcyjnej?

Jest bezpieczne tylko wtedy, gdy WP_DEBUG_DISPLAY jest jawnie ustawione na false i display_errors jest ustawione na 0. Bez tych dwóch ustawień błędy PHP — w tym wewnętrzne ścieżki plików i nazwy tabel bazy danych — są renderowane bezpośrednio w źródle HTML każdej strony. Zawsze łącz WP_DEBUG true z WP_DEBUG_DISPLAY false na każdej stronie z publicznym ruchem.

Dlaczego mój plik debug.log jest pusty, mimo że WP_DEBUG jest włączone?

Najczęstsze przyczyny to: proces serwera WWW nie ma uprawnień do zapisu w katalogu /wp-content/; WP_DEBUG_LOG jest ustawione na false lub brakuje go w wp-config.php; lub błąd występuje na poziomie serwera przed załadowaniem WordPress, co oznacza, że pojawi się w logu Apache lub PHP-FPM, a nie w debug.log. Sprawdź uprawnienia katalogu za pomocą ls -la wp-content/ i zweryfikuj, czy stałe są zdefiniowane we właściwej kolejności w wp-config.php.

Jaka jest różnica między WP_DEBUG_LOG a logiem błędów PHP serwera?

WP_DEBUG_LOG to stała na poziomie WordPress, która kieruje błędy przechwycone przez niestandardowy handler błędów WordPress do debug.log. Log błędów PHP serwera (konfigurowany przez error_log w php.ini) przechwytuje wszystkie błędy PHP na poziomie interpretera, w tym te, które występują przed inicjalizacją WordPress. Na prawidłowo skonfigurowanym serwerze oba logi są aktywne jednocześnie i uzupełniają się nawzajem.

Czy mogę włączyć logowanie błędów na hostingu współdzielonym bez dostępu SSH?

Tak. Możesz edytować wp-config.php przez Menedżer plików swojego dostawcy hostingu w cPanel lub Plesk, włączyć WP_DEBUG i WP_DEBUG_LOG, a następnie odczytać debug.log przez ten sam interfejs Menedżera plików. W przypadku logów na poziomie serwera na Hostingu współdzielonym użyj sekcji Błędy w obszarze Metryki w cPanel. Jeśli potrzebujesz bardziej szczegółowej kontroli nad konfiguracją PHP i ścieżkami logów, przejście na plan Hostingu VPS zapewnia bezpośredni dostęp do php.ini i pełny dostęp SSH do wszystkich plików logów.