Włączanie pliku debug.log WordPress (tryb debugowania WordPress)

Gdy otwierasz swoją witrynę WordPress i widzisz pustą stronę lub błąd 500, WordPress ukrywa komunikat o błędzie, który natychmiast wskazałby przyczynę. Włączenie pliku debug.log WordPress nakazuje WordPressowi zapisywać każdy błąd PHP, ostrzeżenie i powiadomienie do pliku — wp-content/debug.log — dzięki czemu dokładnie zobaczysz, który plugin, motyw czy linia kodu odpowiada za problem.

TL;DR: Dodaj te trzy stałe do wp-config.php, bezpośrednio nad linią /* That's all, stop editing! Happy publishing. */ — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); i define( 'WP_DEBUG_DISPLAY', false );. Po zapisaniu przeładuj stronę, a WordPress zapisze wszystkie błędy PHP do wp-content/debug.log. Po zakończeniu diagnostyki wyłącz tryb debugowania WordPress przed pushem na produkcję.

Tryb debugowania WordPress według środowiska hostingu

Sposób, w jaki uzyskujesz dostęp do wp-config.php — i miejsce, gdzie ląduje debug.log — zależy od twojego środowiska hostingowego. Skorzystaj z sekcji odpowiadającej twojej konfiguracji.

Hosting współdzielony (cPanel / FTP)

Na hostingach współdzielonych, takich jak Bluehost, SiteGround czy Hostinger, wp-config.php znajduje się w katalogu głównym WordPressa, zazwyczaj public_html/. Edytuj go z poziomu File Managera w cPanelu lub klientem FTP, np. FileZilla.

Częsty problem z uprawnieniami: jeśli WordPress nie może zapisać debug.log, katalog wp-content/ musi być zapisywalny dla serwera www. Standardowe uprawnienia katalogów to 755. Nie ustawiaj 777 na hostingu współdzielonym — to czyni katalog zapisywalnym dla wszystkich i jest zagrożeniem bezpieczeństwa.

Według zgłoszeń wsparcia WP STAGING to właśnie hosting współdzielony jest miejscem, gdzie debug.log najczęściej zawodzi po cichu, ponieważ wiele hostingów przechwytuje błędy PHP we własnym logu serwerowym, zamiast pozwolić WordPressowi utworzyć debug.log. Jeśli plik nigdy się nie pojawia po włączeniu WP_DEBUG, zapytaj swojego hosta, gdzie przechowywany jest log błędów PHP.

VPS / serwer zarządzany (SSH)

Mając dostęp SSH, edytuj wp-config.php bezpośrednio z linii poleceń:

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

Po zapisaniu śledź log w czasie rzeczywistym, by obserwować błędy w momencie ich wystąpienia:

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

Jeśli debug.log nie zostanie utworzony, sprawdź, czy katalog wp-content/ jest własnością użytkownika serwera www (www-data na Ubuntu/Debian, apache lub nginx na CentOS/AlmaLinux):

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Lokalny development (LocalWP / DevKinsta / XAMPP)

debug.log pojawia się w tej samej lokalizacji wp-content/debug.log, ale ścieżka bazowa zależy od twojego lokalnego środowiska:

• LocalWP: ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta: ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP w Windowsie: C:xampphtdocs<site-name>wp-contentdebug.log

Środowiska lokalne rzadko mają problemy z uprawnieniami, ponieważ serwer www i twoje konto użytkownika działają jako ten sam proces. Jeśli debug.log nigdy się nie pojawia, sprawdź, czy plik wp-config.php znajduje się w katalogu głównym WordPressa, a nie w katalogu nadrzędnym.

Witryna Staging WP STAGING

Z naszych testów z WP STAGING wynika, że włączanie trybu debug na klonie Staging to najbezpieczniejsze podejście — klon to dokładna kopia witryny produkcyjnej, więc wszelkie odtworzone błędy będą odpowiadały środowisku produkcyjnemu, nie wpływając na prawdziwych odwiedzających.

Aby włączyć tryb debug na witrynie Staging, edytuj wp-config.php wewnątrz katalogu Staging. WP STAGING tworzy witrynę Staging jako oddzielny podkatalog lub subdomenę z własnym wp-config.php, więc zmiany tam nie wpływają na ustawienie WP_DEBUG witryny produkcyjnej.

Jeśli nie możesz zalogować się do witryny Staging, log debug to pierwsze miejsce, w którym warto sprawdzić — błędy logowania na Staging to najczęściej błędy krytyczne PHP, które pojawiają się tylko w logu.

Jak aktywować tryb debugowania WordPress

Możesz włączyć "tryb debug" WordPressa, edytując kilka linii w pliku wp-config.php twojej instalacji WordPressa:

1. Zaloguj się do cPanelu lub na swoją witrynę przez FTP.
2. Użyj File Managera cPanelu lub klienta FTP i edytuj plik wp-config.php.
3. Skopiuj poniższe linie do pliku wp-config.php lub, jeśli już istnieją, zmień ich wartości na true:

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

Uwaga: skopiuj linie dokładnie tak, jak są pokazane, i nie pomijaj średnika ani innych znaków!

1. Wklej skopiowane linie bezpośrednio nad linią, która brzmi
   /* That's all, stop editing! Happy publishing. */

Po przeładowaniu witryny WordPress zapisze wszystkie błędy PHP do pliku debug.log.
WordPress zapisuje ten plik w folderze wp-content/debug.log.

Wyświetlanie błędów we frontendzie WordPress

Jeśli zamiast aktywować plik debug.log chcesz widzieć błędy debug bezpośrednio na ekranie, zmień linię define( 'WP_DEBUG_DISPLAY', false );

Na: define( 'WP_DEBUG_DISPLAY', true );.

WordPress nie tworzy pliku debug.log

Niektórzy dostawcy hostingu[1] nie pozwalają na tworzenie pliku WordPress debug.log. Przechwytują wszystkie błędy PHP i pozwalają WordPressowi zapisywać je do osobnego pliku logu.

Jeśli WordPress nie może utworzyć debug.log, przejdź przez to drzewo decyzyjne, by znaleźć przyczynę:

1. Poszukaj alternatywnego pliku logu. Sprawdź katalog główny witryny pod kątem pliku o nazwie error_log lub poszukaj folderu /logs/. Wiele hostingów współdzielonych, w tym HostGator, przekierowuje błędy PHP do własnego logu serwerowego zamiast pozwolić WordPressowi zapisać debug.log. Jeśli nie znajdziesz żadnych plików logu, zapytaj swojego dostawcę hostingu, gdzie przechowywane są logi błędów PHP.

2. Sprawdź uprawnienia katalogu. wp-content/ musi być zapisywalny dla serwera www. Na serwerze z dostępem SSH uruchom:

ls -la /path/to/wp-content/

Katalog powinien być własnością www-data (Ubuntu/Debian) lub apache (CentOS). Standardowe uprawnienia to 755. Jeśli katalog jest własnością root, a użytkownik serwera www nie może w nim zapisywać, debug.log po cichu się nie utworzy.

3. Sprawdź, czy display_errors nie nadpisuje twoich ustawień. Niektóre konfiguracje serwera php.ini lub dyrektywy .htaccess ustawiają php_flag display_errors Off, co może tłumić output nawet gdy WP_DEBUG_DISPLAY ma wartość true. Sprawdź ustawienia PHP w panelu hostingu lub zapytaj swojego hosta.

4. Sprawdź, czy plugin must-use nie tłumi błędów. Pliki w wp-content/mu-plugins/ ładują się przed wszystkim innym i mogą nadpisywać obsługę błędów WordPressa. Jeśli twój host zainstalował plugin must-use, który przechwytuje błędy, może to uniemożliwić zapis debug.log. Sprawdź pliki w wp-content/mu-plugins/, jeśli ten katalog istnieje.

5. Sprawdź poziom error_reporting. Jeśli error_reporting jest ustawiony zbyt restrykcyjnie — na przykład tylko na E_ERROR — PHP nie będzie logował ostrzeżeń i powiadomień. WordPress ustawia error_reporting(E_ALL), gdy WP_DEBUG ma wartość true, ale plugin lub konfiguracja serwera mogą to zmienić po załadowaniu WordPressa. Pełną listę stałych i informacji, co obejmuje każdy poziom, znajdziesz w dokumentacji PHP error_reporting.

6. Sprawdź, czy katalog ścieżki logu istnieje. Jeśli już ustawiłeś WP_DEBUG_LOG na niestandardową ścieżkę, sprawdź, czy katalog pod tą ścieżką istnieje i jest zapisywalny dla serwera www.

Alternatywnie możesz użyć opisanej powyżej metody i zmienić
define( 'WP_DEBUG_DISPLAY', false ); na
define( 'WP_DEBUG_DISPLAY', true );

Jeśli to zadziała, zobaczysz odpowiednie błędy we frontendzie. To pomoże ci rozwiązać błąd krytyczny.

Bardziej szczegółowe instrukcje dotyczące włączania trybu debug WordPress znajdziesz w dokumentacji debugowania WordPress.

W momencie pisania tego artykułu: [1] HostGator

Alternatywna metoda debugowania błędów krytycznych, gdy debug.log nie jest generowany

Czasami, gdy włączasz tryb WP_DEBUG, by zdiagnozować błąd krytyczny, może się okazać, że twój dostawca hostingu blokuje tworzenie pliku debug.log. Nawet ustawienie WP_DEBUG_DISPLAY na true nie zawsze pomaga pokazać błąd we frontendzie.

Jeśli utkniesz w takiej sytuacji, oto obejście, które działa, gdy nic innego nie pomaga.

Wymuszenie wyświetlenia błędu w wp-config.php

Ten snippet wymusza wyświetlenie błędu krytycznego:

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 Pamiętaj, by usunąć snippet po zakończeniu debugowania i używać go tylko wtedy, gdy masz dostęp FTP, by móc bezpiecznie wycofać zmiany.

Odczytywanie pliku debug.log WordPress

Gdy debug.log już istnieje, otwórz go w dowolnym edytorze tekstu. Każda linia ma format:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Oto co oznacza każda klasa błędu i kiedy na nią reagować:

PHP Fatal error — PHP przerwał wykonywanie. To zawsze przyczyna pustej strony lub błędu 500. Ścieżka pliku i numer linii w logu wskazują dokładnie, gdzie szukać. Znajdź plugin lub motyw, którego plik jest wskazany w logu, i wyłącz go, by to potwierdzić.

PHP Warning — PHP napotkał coś nieoczekiwanego, ale działał dalej. Ostrzeżenia same w sobie nie powodują pustych stron, ale często wskazują błąd, który w innych warunkach stanie się błędem krytycznym. Jeśli włączasz log debug WordPress, by zidentyfikować ostrzeżenia PHP związane z limitami konfiguracji PHP, częstym wpisem jest ostrzeżenie max_input_vars z pluginu obfitującego w formularze.

PHP Notice — PHP zauważył potencjalny problem, np. niezdefiniowaną zmienną. Powiadomienia rzadko wskazują na realny błąd produkcyjny, ale jeśli to samo powiadomienie pojawia się tysiące razy na jedno załadowanie strony, może to świadczyć o problemie z pętlą lub rekurencją obniżającym wydajność.

Błędy bazy danych $wpdb — linie zaczynające się od WordPress database error oznaczają, że zapytanie się nie powiodło. Zazwyczaj wskazują plugin generujący błędne zapytanie SQL lub problem w tabelach bazy danych WordPress, do których odnosi się zapytanie. Komunikat błędu zawiera zapytanie, które się nie powiodło, co ułatwia identyfikację winowajcy.

Gdy znajdziesz błąd krytyczny lub powtarzające się ostrzeżenie, spójrz na ścieżkę pliku w logu. Jeśli należy do pluginu lub motywu, wyłącz go, przeładuj stronę i sprawdź, czy wpisy logu się zatrzymały.

Jeśli log debug ujawnia błędy REST API w WordPress, wpis logu zwykle wskazuje dokładną funkcję, która zawiodła — od tego miejsca podążaj zgodnie z dedykowanym przewodnikiem. Jeśli ujawnia błędy ERR_CONNECTION_REFUSED, pochodzą one z warstwy serwera lub sieci, a nie z PHP. W przypadku błędów 414 Request-URI Too Large log zwykle identyfikuje plugin generujący zbyt długi URL.

Zmiana lokalizacji pliku debug.log

Możesz zmienić ścieżkę, której WordPress używa do logowania błędów, zmieniając wartość stałej WP_DEBUG_LOG.

Otwórz wp-config.php i znajdź linię zawierającą WP_DEBUG_LOG.

Wyszukaj: define( 'WP_DEBUG_LOG', true );

Zmień na: define( 'WP_DEBUG_LOG', '/logs/errors.log' );

Pozwala to WordPressowi zapisywać komunikaty błędów do innej ścieżki pliku.

Jako ścieżkę docelową możesz też użyć /dev/stderr lub /dev/stdout. Jest to przydatne w Dockerze lub innych środowiskach kontenerowych, gdy chcesz mieć wszystkie logi we wspólnym strumieniu wyjściowym.

Wyłącz tryb debug w WordPress po diagnostyce

Gdy zakończysz dochodzenie, natychmiast wyłącz tryb debug. Plik debug.log jest domyślnie dostępny z poziomu sieci pod adresem wp-content/debug.log i może zawierać szczegóły błędów bazy danych, ścieżki plików oraz inne informacje serwerowe, które nie powinny być publicznie czytelne.

Usuń plik debug.log i wyłącz dalsze logowanie błędów, zmieniając define( 'WP_DEBUG', true ); z powrotem na define( 'WP_DEBUG', false );.

Pracując na witrynie Staging, zawsze wyłącz tryb debug WordPress przed pushem na produkcję. Workflow pushu WP STAGING to właściwy moment, by upewnić się, że WP_DEBUG jest wyłączone, zanim klon nadpisze witrynę produkcyjną.

Powiązane artykuły

• Pusta biała strona na witrynie Staging WordPress
• Jak naprawić błąd 500 i pustą białą stronę WordPress
• Jak debugować błędy JavaScript w konsoli przeglądarki