Biały ekran śmierci PrestaShop: przewodnik naprawy krok po kroku

Tak zwany biały ekran śmierci PrestaShop to pusta strona bez żadnego komunikatu – we front office, panelu administracyjnym (Back Office) lub obu naraz. Zazwyczaj oznacza to, że PHP zatrzymało się, zanim sklep zdążył wygenerować kod HTML. Ten przewodnik pokazuje, jak włączyć tryb debugowania (nawet gdy panel nie działa), odczytać prawdziwy błąd i wdrożyć poprawki, które rozwiązują większość przypadków WSoD.

Od wersji PrestaShop 1.7 (w tym 8 i 9), przełączniki debugowania znajdują się w sekcji Zaawansowane → Wydajność, jeśli panel administracyjny (Back Office) wciąż się ładuje. Jeśli panel też jest pusty, należy przełączyć _PS_MODE_DEV_ w pliku config/defines.inc.php przez SFTP lub SSH. Oficjalne notatki dotyczące tych ustawień można znaleźć w dokumentacji PrestaShop 9 (Performance). Należy wykonać pełną kopię zapasową PrestaShop przed usunięciem modułów lub przywracaniem plików.

Co zazwyczaj oznacza biały ekran śmierci PrestaShop

Pusta strona to objaw, a nie jeden konkretny błąd. Pojawiający się biały ekran śmierci PrestaShop oznacza, że PHP napotkało błąd krytyczny (fatal error), zabrakło pamięci lub wystąpiła awaria, zanim silnik Smarty mógł cokolwiek wyświetlić. Tryb produkcyjny celowo ukrywa te szczegóły, aby kupujący nigdy nie zobaczyli śladu stosu (stack trace). Zadaniem jest uwidocznienie błędu, a następnie naprawienie jego przyczyny.

Warto zwrócić uwagę na to, gdzie występuje problem:

• Tylko strona frontowa – często to nadpisanie (override) szablonu, zaczep (hook) modułu lub pozostałość w pamięci podręcznej (cache) na froncie sklepu
• Tylko Back Office – często moduł administracyjny, zakładka lub nadpisanie w katalogu override/
• Oba naraz – błędne dane logowania do bazy danych, uszkodzony plik defines.inc.php, awaria wersji PHP lub błąd krytyczny uruchamiający się przy każdym żądaniu

Krok 1: Włącz tryb debugowania

Tryb debugowania wyświetla wyjątek (lub wskazuje log), zamiast białej strony. Preferuj włączenie go w panelu administracyjnym, jeśli ten nadal działa.

1. Zaloguj się do panelu administracyjnego (Back Office).
2. Przejdź do Zaawansowane → Wydajność.
3. W sekcji Tryb debugowania, ustaw Tryb debugowania na Tak.
4. Kliknij Zapisz.
5. Odśwież niedziałający adres URL w oknie prywatnym.

Jeśli panel administracyjny to również biały ekran śmierci PrestaShop, edytuj plik na dysku. Najpierw pobierz kopię pliku config/defines.inc.php (nawet jeśli istnieje już pełna kopia zapasowa sklepu), aby w razie pomyłki można było przywrócić oryginał jednym kliknięciem:

1. Otwórz config/defines.inc.php przez SFTP, SSH lub menedżera plików hostingu i zapisz lokalną kopię.
2. Znajdź linię define('_PS_MODE_DEV_', false); (sformułowanie może się nieznacznie różnić w zależności od wersji).
3. Zmień ją na define('_PS_MODE_DEV_', true); i zapisz.
4. Odśwież niedziałającą stronę.

Wyłącz tryb debugowania po zakończeniu pracy. Pozostawienie go włączonego w środowisku produkcyjnym ujawnia ścieżki i ślady stosu każdemu, kto napotka błąd.

Krok 2: Zidentyfikuj błąd

Po włączeniu debugowania, biały ekran śmierci PrestaShop zazwyczaj zmienia się w czytelny komunikat o wyjątku. Zwróć uwagę na nazwę klasy, nazwę modułu, ścieżkę do pliku w modules/, themes/ lub override/ oraz numer linii. Ten ciąg znaków zazwyczaj wystarczy, aby wybrać odpowiednie rozwiązanie z poniższych.

Jeśli strona pozostaje pusta nawet po ustawieniu _PS_MODE_DEV_ na true, sprawdź log błędów PHP na hostingu (cPanel, Plesk lub var/logs/ w niektórych konfiguracjach). Błąd składni (parse error) w pliku konfiguracyjnym może przerwać działanie, zanim uruchomi się warstwa debugowania PrestaShop.

Najczęstsze źródła problemów:

• Ostatnie modyfikacje – edycje szablonu, nadpisania (overrides) lub skopiowane fragmenty kodu
• Moduły – zwłaszcza moduł zainstalowany lub zaktualizowany tuż przed awarią
• Zmiany na hostingu – podniesienie wersji PHP, brakujące rozszerzenie, niższy limit pamięci
• Dane logowania do bazy danych – błędne wartości w app/config/parameters.php po migracji
• Uprawnienia plików – PHP nie może odczytać wymaganego pliku lub zapisać pamięci podręcznej
• Limit pamięci – błędy krytyczne wspominające o wyczerpaniu pamięci (memory exhausted)
• Nieaktualny cache – uszkodzone skompilowane szablony po aktualizacji

Krok 3: Napraw błąd

Wynik debugowania należy dopasować do jednej ze ścieżek. Warto zmieniać tylko jedną rzecz naraz, a następnie odświeżać stronę.

Modyfikacje i nadpisania

Ostatnią zmianę w szablonie lub nadpisaniu należy cofnąć, jeśli jest znana. Na stronie Wydajność, spróbuj ustawić Wyłącz wszystkie nadpisania → Tak, zapisz i przetestuj ponownie. Jeśli sklep wraca do działania, błąd znajduje się w katalogu override/ lub nadpisaniu modułu – napraw lub usuń ten plik, zamiast zostawiać nadpisania wyłączone na zawsze.

Błędy modułów

Na stronie Wydajność ustaw Wyłącz moduły niepochodzące od PrestaShop → Tak i przetestuj ponownie. Jeśli to rozwiąże biały ekran śmierci PrestaShop, należy zmieniać nazwy folderów podejrzanych modułów w modules/ (lub odinstaluj je z poziomu panelu administracyjnego, gdy zacznie działać) jeden po drugim, aż znajdziesz winowajcę. Preferuj zmianę nazwy zamiast usuwania, aby móc przywrócić pliki po zidentyfikowaniu problemu.

Hosting i PHP

Porównaj zakładkę Zaawansowane → Informacja z tym, co deklaruje hosting. Po aktualizacji PHP, brakujące rozszerzenia lub bardziej restrykcyjna obsługa błędów często objawiają się jako pusta strona. Warto zapytać dostawcę hostingu, jakiej wersji PHP i memory_limit faktycznie używa vhost.

Połączenie z bazą danych

Jeśli debugowanie wskazuje na dostęp do bazy danych lub sklep przestał działać zaraz po przeniesieniu na inny serwer, zweryfikuj hosta, nazwę, użytkownika i hasło w pliku app/config/parameters.php. Pełne instrukcje znajdują się w naszym poradniku dotyczącym zmiany ustawień połączenia z bazą danych w PrestaShop.

Uprawnienia i pamięć

Gdy błąd wskazuje plik, którego PHP nie może otworzyć, napraw właściciela i uprawnienia dla tej ścieżki (zazwyczaj właściciel to użytkownik serwera WWW; unikaj 777 jako trwałego rozwiązania). W przypadku błędów wyczerpania pamięci, podnieś memory_limit w pliku php.ini hosta wirtualnego lub poproś o to hosting – następnie wyczyść cache i przetestuj ponownie.

Pamięć podręczna (Cache)

W sekcji Wydajność kliknij Wyczyść pamięć podręczną. Jeśli panel administracyjny nie działa, usuń zawartość folderu var/cache/prod/ (oraz var/cache/dev/, jeśli istnieje) przez menedżera plików lub SSH, zachowując same foldery. Ogromne drzewa plików cache są często łatwiejsze do usunięcia przez SSH niż przez FTP.

Krok 4: Gdy nadal potrzebujesz pomocy

Jeśli debugowanie jest włączone, moduły i nadpisania są odizolowane, dane logowania poprawne, a biały ekran śmierci PrestaShop nadal się pojawia, należy zebrać: dokładny tekst błędu, wersję PrestaShop, wersję PHP oraz informację, co ostatnio uległo zmianie (moduł, wdrożenie, aktualizacja hostingu). Zebrane informacje warto opublikować na forach PrestaShop lub wysłać do hostingu bądź programisty, który może odczytać logi serwera, niewidoczne z poziomu samego sklepu.

Krok 5: Przywróć kopię zapasową

Przywracanie plików lub zrzutu bazy danych to ostateczność – tracisz wtedy zmiany wprowadzone po jej wykonaniu. Rozwiązanie to stosuje się, gdy nie można szybko wycofać błędnego wdrożenia, a posiadasz niedawną kopię. Sposoby tworzenia i przechowywania tych kopii opisano w przewodniku o tworzeniu kopii zapasowych PrestaShop.

Szybka lista kontrolna

1. Włącz debugowanie (panel administracyjny Wydajność lub _PS_MODE_DEV_ w pliku defines.inc.php).
2. Odczytaj błąd na ekranie lub w logu PHP.
3. Wyizoluj nadpisania i moduły obce z poziomu strony Wydajność.
4. Napraw dane bazy danych, uprawnienia, pamięć lub cache, jak wskazuje komunikat.
5. Wyłącz debugowanie; przywróć kopię zapasową tylko wtedy, gdy nic innego nie przywraca działania sklepu.

Większość przypadków, w których pojawia się biały ekran śmierci PrestaShop, udaje się rozwiązać po wyświetleniu prawdziwego komunikatu PHP. Należy zacząć od trybu debugowania, zmieniać jedną zmienną naraz i mieć w gotowości kopię zapasową przed usunięciem czegokolwiek, czego nie da się przywrócić.