Jak debugować błędy WordPress

Awaria strony oparta na WordPressie potrafi sparaliżować biznes i komunikację. Zamiast działać po omacku, warto poznać konkretne kroki, które pozwalają szybko zlokalizować i usunąć problem. Poniższa instrukcja prowadzi od włączenia narzędzi diagnostycznych, przez analizę przyczyn, aż po bezpieczne wdrożenie poprawek. Skupiamy się na praktyce: co ustawić, co sprawdzić i jak nie pogorszyć sytuacji podczas pracy nad usterką.

Włączenie i konfiguracja trybu debugowania

Podstawowe stałe i przygotowanie środowiska

Na czas debugowanie błędów w WordPressie włącz tryb diagnostyczny. Edytuj plik wp-config.php (zwykle w katalogu głównym strony). Jeśli nie istnieją, dodaj poniższe linie tuż nad komentarzem informującym o końcu edycji (/* That’s all, stop editing! Happy publishing. */):

• define(’WP_DEBUG’, true); — podstawowa flaga włączająca tryb debug; pierwsze i najważniejsze ustawienie to WP_DEBUG.
• define(’WP_DEBUG_LOG’, true); — zapisuje błędy do pliku wp-content/debug.log.
• define(’WP_DEBUG_DISPLAY’, false); — wyłącza wyświetlanie błędów w HTML; na produkcji to bezpieczniejsze podejście.
• define(’SCRIPT_DEBUG’, true); — ładuje nieskompresowane wersje skryptów, ułatwia analizę JS i CSS.
• define(’SAVEQUERIES’, true); — rejestruje zapytania do bazy wraz z czasem wykonania (pamiętaj, aby wyłączyć po testach).

Jeśli pracujesz w panelu hostingu, sprawdź również ustawienia PHP (error_reporting, log_errors). Zalecane: error_reporting = E_ALL, log_errors = On, display_errors = Off na środowisku produkcyjnym i On tylko na środowisku testowym.

Rejestrowanie błędów do pliku i interpretacja

Po włączeniu logowania błędów szukaj pliku wp-content/debug.log. Jeśli się nie tworzy, upewnij się, że katalog wp-content ma poprawne uprawnienia. Najczęściej 755 dla katalogów i 644 dla plików wystarcza (nie ustawiaj 777). W debug.log szukaj linii z typami: PHP Fatal error, PHP Warning, PHP Notice, Deprecated. Najgroźniejsze są „Fatal error”, bo wstrzymują działanie strony, ale ostrzeżenia też potrafią sygnalizować konflikt lub przestarzały kod.

Wpisy debug.log zwykle zawierają: datę, typ błędu, opis oraz ścieżkę pliku i numer linii. Postępuj tak:

• Zidentyfikuj komponent (wtyczka, motyw, plik rdzenia) w ścieżce.
• Sprawdź, czy błąd pojawia się przy każdym odświeżeniu czy tylko w określonych okolicznościach (np. po wysłaniu formularza).
• Skopiuj fragment błędu i wyszukaj znane rozwiązania, ale konfrontuj je z posiadaną wersją WP i PHP.

Debugowanie JavaScript i CSS

Jeśli problem dotyczy interfejsu (brak reakcji przycisków, błędne działanie edytora), otwórz narzędzia deweloperskie przeglądarki (zwykle F12). Karta Console wykaże błędy JS, a Network pokaże żądania 404 lub 403. Po włączeniu SCRIPT_DEBUG przeładowuj stronę z opróżnioną pamięcią podręczną (tryb prywatny lub twarde odświeżenie). Zwróć uwagę na mieszane treści (HTTP/HTTPS) i blokady CORS.

Typowe pułapki i bezpieczeństwo

• Nie pozostawiaj debugowania włączonego na stałe: po naprawie przywróć WP_DEBUG do false i wyłącz SAVEQUERIES/SCRIPT_DEBUG.
• Nie wyświetlaj błędów użytkownikom: WP_DEBUG_DISPLAY powinno być false na produkcji.
• Dbaj o dane wrażliwe: zrzuty błędów mogą ujawniać ścieżki, strukturę bazy i sekrety; trzymaj je poza publicznym repozytorium.

Izolacja problemu w bezpiecznym miejscu

Najlepiej testować na kopii strony. Utwórz środowisko staging w panelu hostingu lub ręcznie: skopiuj pliki, zrzut bazy i skonfiguruj wp-config.php (zmień prefiks tabel, dane dostępu i adres URL). W stagingu uruchamiaj debug, aktualizacje i eksperymenty bez ryzyka przerwy w działaniu serwisu produkcyjnego.

Diagnozowanie błędów rdzenia, motywów i wtyczek

Białe ekrany i błędy krytyczne

„Biały ekran śmierci” lub komunikat o krytycznym błędzie zwykle oznacza PHP Fatal error. Najpierw sprawdź debug.log i logi serwera. Jeśli nie masz dostępu do kokpitu, spróbuj tymczasowo wyłączyć wszystkie wtyczki i przełączyć motyw z poziomu FTP/SFTP:

• Zmiana nazwy katalogu wp-content/plugins na plugins.off spowoduje dezaktywację wszystkich wtyczek.
• Jeśli strona ruszy, przywróć nazwę i wyłączaj wtyczki pojedynczo, zmieniając nazwy ich katalogów, by znaleźć winowajcę.
• Aby wymusić motyw domyślny, zmień nazwę aktywnego motywu w wp-content/themes. WordPress załaduje motyw Twenty Twenty‑x, o ile jest dostępny.

Gdy odzyskasz dostęp do kokpitu, użyj trybu rozwiązywania problemów (np. wtyczka Health Check & Troubleshooting), który dezaktywuje rozszerzenia tylko dla Twojej sesji, co pozwala diagnozować bez wpływu na użytkowników.

Konflikty i kompatybilność wersji

• PHP: upewnij się, że wersja jest wspierana przez Twoje wtyczki/motyw. Błędy typu „Call to undefined function” często wynikają z uruchamiania kodu na zbyt starej wersji PHP.
• WordPress: niektóre wtyczki wymagają minimum konkretnej wersji WP. Sprawdź wymagania i historię zmian.
• Aktualizacje: po aktualizacji wtyczki lub motywu szybko sprawdź logi i kluczowe funkcje witryny. Rozważ włączenie automatycznych aktualizacji tylko dla sprawdzonych komponentów.

Praca z motywami: dziedziczenie i modyfikacje

Modyfikowanie plików motywu nadrzędnego utrudnia aktualizacje i diagnozę, bo zmiany mogą się nadpisywać. Zawsze twórz motyw potomny. Jeśli błąd występuje po modyfikacjach, porównaj różnice z oryginałem (np. Git diff) i tymczasowo cofnij podejrzane fragmenty. Sprawdź pliki functions.php, template‑parts i własne shortcody.

Problemy z bazą danych i zapytaniami

• Jeśli widzisz „Error establishing a database connection”, zweryfikuj w wp-config.php: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST oraz dostęp z hostingu.
• Wolne ładowanie stron może oznaczać ciężkie zapytania. Tymczasowo włącz SAVEQUERIES lub użyj narzędzi z kolejnej sekcji, aby sprawdzić czas i liczbę zapytań.
• W razie podejrzeń o uszkodzenie tabel użyj (tylko na chwilę!) define(’WP_ALLOW_REPAIR’, true); i odwiedź /wp-admin/maint/repair.php, a po zakończeniu usuń tę linię.

Uprawnienia, limity i cache

• Uprawnienia plików: brak możliwości zapisania do wp-content/uploads, błędy przy aktualizacji lub brak debug.log często wynikają z błędnych uprawnień lub właściciela plików.
• Limity PHP: memory_limit, max_execution_time, max_input_vars. Zbyt niskie wartości powodują przerwania procesów (np. importów). Podnieś je rozsądnie i monitoruj skutki.
• Cache: po zmianach czy wyłączeniu wtyczek zawsze czyść cache (wtyczki cache, serwer Varnish, CDN). Zastane pliki mogą maskować lub utrwalać błąd.

Narzędzia i techniki analizy

Pluginy diagnostyczne i pomiary

W instalacji deweloperskiej zainstaluj wtyczkę Query Monitor. Wyświetla błędy PHP, ostrzeżenia, zapytania SQL (z czasem i źródłem), haki, obciążenie pamięci, opóźnione żądania HTTP, błędy REST API i błędy bloków edytora. Dzięki temu szybko sprawdzisz, który komponent generuje najcięższe zapytania i co faktycznie spowalnia stronę.

Inne praktyczne narzędzia: wtyczki do logowania żądań mailowych (aby wykryć problemy z wysyłką), inspektory CRON (pokażą zaległe zadania), a także moduły sprawdzające zgodność wersji PHP.

Automatyzacja i wiersz poleceń

Jeśli masz dostęp do SSH, użyj WP-CLI do szybkiej diagnostyki i napraw:

• wp core verify-checksums — wykrywa zmodyfikowane pliki rdzenia.
• wp plugin list — zobaczysz wersje, status i dostępne aktualizacje; wp plugin deactivate –all i selektywna aktywacja ułatwia izolację konfliktu.
• wp theme activate twentyseventeen (lub inny motyw domyślny) — błyskawiczne sprawdzenie, czy motyw jest przyczyną.
• wp transient delete –all — czyści chwilowe dane, które mogą powodować niespójności.
• wp option get siteurl oraz home — wykryjesz błędne adresy po migracji.

Debugowanie krok po kroku i Xdebug

W środowisku lokalnym skonfiguruj Xdebug w PHP, aby zatrzymywać wykonanie kodu na punktach przerwania. To najskuteczniejsza metoda śledzenia, gdzie naprawdę dochodzi do awarii lub złych danych. Połącz IDE (np. PhpStorm, VS Code) z serwerem, ustaw breakpoint w funkcji zgłaszającej błąd i prześledź wartości zmiennych, stos wywołań i ścieżki warunków. Dodatkowo włącz profiling, by uzyskać wykresy czasu wykonania funkcji (np. wyświetlane w narzędziach KCachegrind/qcachegrind).

Analiza zaplecza serwera i logi

Poza debug.log WordPressa sprawdzaj logi serwera WWW i PHP. Na typowych instalacjach znajdziesz je w katalogach serwera (np. /var/log/nginx/error.log, /var/log/apache2/error.log, logi PHP-FPM). Te pliki ujawnią błędy modułów, problemy z uprawnieniami, przekroczenia limitów czasu oraz błędy na poziomie reverse proxy lub CDN. Zwróć uwagę na kody odpowiedzi 499/502/504, które mogą wskazywać timeouty lub problemy z komunikacją między warstwami infrastruktury.

Diagnostyka frontendu i API

• REST API: sprawdź odpowiedzi z /wp-json/ — błędy 401/403/500 podpowiedzą, czy winne są uprawnienia, nonce lub konflikt wtyczek bezpieczeństwa.
• Blokady CORS: upewnij się, że nagłówki Access-Control-Allow-Origin są prawidłowe, zwłaszcza przy headless WP lub zewnętrznych integracjach.
• Assets: błędy 404 dla skryptów/style.css zwykle wynikają z niepoprawnych ścieżek po migracji lub zablokowanych katalogów.

Procedury bezpiecznego testowania i wdrażania poprawek

Kopia zapasowa i kontrola wersji

Zanim cokolwiek zmienisz, wykonaj pełny backup: pliki + baza. W projektach utrzymuj repozytorium Git: motywy własne, wtyczki autorskie i konfiguracje wdrożeniowe. Każdą zmianę opisuj w commitach i taguj wydania, aby łatwo wrócić do poprzedniej wersji. Dla środowiska produkcyjnego stosuj politykę „no direct edits”: żadne zmiany przez edytor w kokpicie, tylko wdrożenia z repo.

Reprodukcja i plan testów

• Opisz kroki odtwarzające błąd: adres, logowanie, akcje, spodziewany vs obecny rezultat.
• Wybierz minimalny zestaw danych testowych; wyłącz cache, by zobaczyć efekt zmian.
• Ustal kryteria akceptacji: co oznacza, że błąd jest usunięty (np. formularz wysyła e‑mail, rekord zapisuje się w bazie, nie pojawia się ostrzeżenie w debug.log).

Strategie izolacji i testy regresji

Wykorzystuj metodę „binary search”: wyłącz połowę wtyczek, sprawdź wynik, zawężaj grupę winnych. Potem analizuj ich ustawienia i zależności. Gdy naprawiasz błąd, uruchom testy regresji: kluczowe ścieżki użytkownika (logowanie, koszyk, płatność, wyszukiwarka, formularze) i podstrony o największym ruchu. Warto przygotować listę kontrolną dla zespołu, aby po każdej zmianie automatycznie przejść przez te punkty.

Wdrożenie i obserwowalność

• Wdrażaj zmiany partiami, monitorując metryki: czas odpowiedzi, błędy 5xx, obciążenie CPU i RAM, kolejki procesów.
• Skonfiguruj alerty (np. maile/SMS/komunikatory) dla błędów krytycznych i gwałtownych wzrostów czasu odpowiedzi.
• Rozważ centralizację logów i śledzenie wyjątków (stack traces), aby szybciej kojarzyć przyczyny na produkcji.
• Po wdrożeniu usuń dane testowe i wyłącz zbędne tryby diagnostyczne, by nie obciążać serwera i nie generować nadmiarowych logów.

Najczęstsze scenariusze i szybkie recepty

• Po migracji brak stylów/obrazów: zaktualizuj adresy w bazie (siteurl/home), przebuduj permalink (Ustawienia → Bezpośrednie odnośniki → Zapisz), wyczyść cache CDN.
• Problem z uploadem: sprawdź uprawnienia wp-content/uploads i limit post_max_size / upload_max_filesize.
• Timeouty przy imporcie: podnieś max_execution_time, memory_limit, wyłącz intensywne wtyczki cache podczas importu.
• Funkcje przestarzałe: komunikaty Deprecated wskazują na API, które w kolejnych wersjach może zniknąć — zaktualizuj kod, zanim wymusi to nowa wersja WP/PHP.
• Konflikt JS w kokpicie: porównaj listę aktywnych wtyczek, sprawdź konsolę przeglądarki, wyłączaj rozszerzenia ingerujące w edytor blokowy po jednym i testuj.

Przestrzeganie powyższej procedury — od włączenia trybu diagnostycznego i pracy na kopii, przez izolację komponentów i analizę u źródła błędu, po kontrolowane wdrożenie i monitoring — znacząco skraca czas naprawy i minimalizuje ryzyko przestojów. Z czasem utworzysz własny, dopasowany do projektu zestaw narzędzi i checklistę, które pozwolą reagować pewnie nawet w trudnych przypadkach.