Gdzie leży debug.log w WordPressie i jak go przenieść

WordPress domyślnie zapisuje dziennik debugowania do wp-content/debug.log — czyli na dysku pod bezwzględną ścieżką /sciezka/do/twojej/strony/wp-content/debug.log. Plik nie istnieje, dopóki coś faktycznie nie zostanie zapisane, a zapisywane jest tylko wtedy, gdy w wp-config.php WP_DEBUG ma wartość true, a WP_DEBUG_LOG jest włączone. Ta domyślna lokalizacja to również realny problem bezpieczeństwa, bo na większości hostingów każdy może pobrać ten plik w przeglądarce.

Trzy stałe i co robi każda z nich

Wszystkie trzy trafiają do wp-config.php, powyżej linii /* That's all, stop editing! Happy blogging. */. Cokolwiek dodasz poniżej niej, wykona się już po starcie WordPressa i zostanie zignorowane.

Stała	Domyślnie	Co robi
WP_DEBUG	false	Główny włącznik. Podnosi poziom raportowania błędów PHP, żeby pokazywać powiadomienia, ostrzeżenia i informacje o przestarzałym kodzie. Bez niej nic z tej listy nie działa.
WP_DEBUG_LOG	false	Kieruje błędy do pliku. true oznacza wp-content/debug.log. Ciąg znaków jest traktowany jako ścieżka do pliku, w którym ma powstać dziennik.
WP_DEBUG_DISPLAY	true	Wypisuje błędy w kodzie HTML strony, widoczne dla każdego odwiedzającego.

Zależność między nimi to rzecz, którą ludzie najczęściej mylą. WP_DEBUG_LOG jest odczytywane wewnątrz gałęzi WP_DEBUG w kodzie startowym WordPressa. Jeśli WP_DEBUG ma wartość false, ustawienie WP_DEBUG_LOG na true nie zrobi absolutnie nic — żadnego pliku, żadnego błędu, żadnego ostrzeżenia. Jeśli dodałeś WP_DEBUG_LOG, a dziennik się nie pojawił, sprawdź najpierw WP_DEBUG.

Działająca konfiguracja dla witryny produkcyjnej:

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

Jeśli WP_DEBUG jest już zdefiniowane wyżej w pliku — a zwykle jest, z wartością false — popraw tę istniejącą linię, zamiast dopisywać drugie define(). Zdefiniowanie tej samej stałej dwa razy rzuca ostrzeżenie PHP, które na stronie z włączonym wyświetlaniem ląduje dokładnie na jej górze.

Dlaczego WP_DEBUG_DISPLAY musi być wyłączone na produkcji

Przy włączonym wyświetlaniu błędy PHP trafiają do odpowiedzi HTML. Jedno powiadomienie o przestarzałej funkcji w szablonie wypisuje bezwzględną ścieżkę systemu plików twojego serwera każdemu odwiedzającemu. Błąd bazy danych wypisuje nazwy tabel i fragmenty zapytań. Gorzej: treść pojawiająca się przed wysłaniem nagłówków psuje przekierowania, psuje odpowiedzi REST i AJAX, które oczekują czystego JSON-a, i potrafi wywołać biały ekran, o który ludzie potem obwiniają wtyczki.

Jeden niuans warto znać: ustawienie WP_DEBUG_DISPLAY na null to nie to samo co false. null każe WordPressowi nie ruszać ustawienia display_errors w PHP i przejąć to, co skonfigurowano na serwerze. false aktywnie je wyłącza. Na witrynie produkcyjnej użyj false i dorzuć powyższą linię z ini_set jako drugie zabezpieczenie, bo wtyczka może później w trakcie żądania z powrotem włączyć display_errors.

Domyślna lokalizacja jest publicznie dostępna

wp-content/debug.log leży wewnątrz katalogu publicznego. Nic w standardowej instalacji WordPressa nie blokuje bezpośrednich żądań do niego. Na typowej konfiguracji Apache albo nginx adres https://twojastrona.pl/wp-content/debug.log zwraca plik jako zwykły tekst. Dzienniki debugowania zawierają bezwzględne ścieżki serwera, wnętrzności wtyczek i szablonów, błędy bazy danych z prawdziwą treścią zapytań, a czasem wartości przekazane do funkcji, które zawiodły. To darmowy rekonesans dla każdego, kto zgadnie ten adres — a jest to jeden z pierwszych adresów, które sprawdzają automatyczne skanery.

Są dwa sposoby, żeby sobie z tym poradzić. Lepszy to przeniesienie dziennika.

Przenieś dziennik, podając ścieżkę

Od WordPressa 5.1 WP_DEBUG_LOG przyjmuje ścieżkę do pliku jako ciąg znaków zamiast wartości logicznej. Wskaż miejsce poza katalogiem publicznym:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/home/youruser/logs/wp-errors.log' );
define( 'WP_DEBUG_DISPLAY', false );

Trzy zasady dotyczące tej ścieżki. Używaj ścieżki bezwzględnej — względna jest rozwijana względem katalogu roboczego PHP, który zmienia się z żądania na żądanie i z serwera na serwer, więc stracisz orientację, gdzie wylądował plik. Katalog musi już istnieć; PHP go nie utworzy, a jeśli nie zdoła otworzyć pliku, zawiedzie po cichu. I katalog musi być zapisywalny dla użytkownika PHP, który na hostingu współdzielonym nie jest tym samym kontem, którym logujesz się przez SFTP.

Jeśli hosting zamyka cię w katalogu publicznym i nie ma nad nim miejsca do zapisu, zostaw domyślną ścieżkę i zablokuj dostęp na poziomie serwera. Apache:

<Files "debug.log">
  Require all denied
</Files>

To trafia do pliku .htaccess wewnątrz wp-content, a nie do tego w katalogu głównym — WordPress przepisuje główny .htaccess przy zapisywaniu bezpośrednich odnośników i potrafi skasować twój wpis. Na nginx .htaccess nie robi zupełnie nic; potrzebujesz bloku location w konfiguracji serwera, co na hostingu zarządzanym zwykle oznacza prośbę do supportu.

Bądź szczery co do tego, co daje blokada: plik nadal leży na dysku, w katalogu obsługiwanym przez serwer WWW. Błąd typu path traversal w dowolnej wtyczce wciąż pozwoli go odczytać. Przeniesienie poza katalog publiczny to mocniejsze rozwiązanie.

Czytanie i podglądanie pliku na żywo

Przez SSH możesz obserwować go na żywo w trakcie odtwarzania błędu:

tail -f wp-content/debug.log

Wywołaj błąd w drugiej karcie, a nowe linie pojawią się w momencie zapisu. Żeby zobaczyć tylko to, co wydarzyło się niedawno, albo odfiltrować jedną wtyczkę:

tail -n 100 wp-content/debug.log
grep -i 'plugin-slug' wp-content/debug.log | tail -n 50

PHP dopisuje na końcu pliku, więc czytaj od dołu do góry. Każdy wpis ma znacznik czasu w UTC, który nie będzie zgodny ze strefą czasową ustawioną w WordPressie — nie daj się przez to zwieść, że patrzysz na stare wpisy.

Za pomocą WP-CLI możesz przełączać te stałe bez ręcznej edycji pliku:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Flaga --raw ma znaczenie — bez niej wartość zostanie zapisana jako ciąg "true", a nie jako wartość logiczna. Przy wariancie ze ścieżką pomiń --raw, żeby zapisała się jako ciąg w cudzysłowie.

Nie masz SSH? Pobierz plik przez SFTP albo otwórz go w menedżerze plików hostingu. Unikaj wtyczek pokazujących dziennik wewnątrz wp-admin, chyba że masz do nich pełne zaufanie; dajesz wtyczce dostęp do odczytu pliku pełnego wewnętrznych informacji o serwerze.

Jeśli chcesz gotowy blok do wp-config dopasowany do twojej konfiguracji, razem z bezpieczną ścieżką poza katalogiem publicznym i pasującą regułą serwera, zbuduje go za ciebie generator dziennika debugowania WordPressa.

Wyłącz to, kiedy skończysz

Nic w rdzeniu WordPressa nie rotuje ani nie skraca pliku debug.log. Na stronie rzucającej powiadomienie przy każdym wczytaniu rośnie on bez końca i potrafi zapełnić dysk — co kładzie witrynę mocniej niż błąd, który ścigałeś. Włącz logowanie, odtwórz problem, przeczytaj dziennik, a potem ustaw WP_DEBUG z powrotem na false.

Żeby wyczyścić plik bez usuwania go:

: > wp-content/debug.log

Kiedy dziennik pozostaje pusty

Przejdź przez te punkty po kolei. WP_DEBUG ma wartość false — zdecydowanie najczęstsza przyczyna, po cichu wyłączająca całą resztę. Stała jest poniżej linii „stop editing” w wp-config.php. Uprawnienia plików — PHP nie może zapisywać do wp-content ani do wskazanego przez ciebie katalogu. Błąd krytyczny przed zakończeniem wczytywania wp-config, na przykład błąd składni w samym pliku konfiguracyjnym, następuje za wcześnie, żeby logowanie WordPressa go złapało; takie trafiają do dziennika błędów PHP na serwerze. Hosting nadpisuje ustawienia — niektóre platformy zarządzane przypinają ustawienie error_log w PHP albo kierują logi do własnego panelu, więc twoje stałe są ustawione poprawnie, a wynik jest po prostu gdzie indziej. Zajrzyj do przeglądarki logów hostingu, zanim uznasz, że twoja konfiguracja jest zepsuta.