Biała strona w PrestaShop po aktualizacji: Przewodnik odzyskiwania

Dlaczego białe strony pojawiają się po aktualizacjach PrestaShop

Pusta biała strona, często nazywana Białym Ekranem Śmierci (WSOD — White Screen of Death), jest jednym z najczęstszych i najbardziej niepokojących problemów, z jakimi spotykają się właściciele sklepów PrestaShop po aktualizacji oprogramowania rdzenia. Inicjujesz aktualizację z wersji 1.7.8.7 do 1.7.8.8, lub z 8.1.0 do 8.1.5, proces wydaje się zakończony, a następnie cały Twój sklep — zarówno front office, jak i back office — wyświetla jedynie biały ekran. Żadnego komunikatu o błędzie, żadnej częściowej treści, tylko pustka.

Zrozumienie, dlaczego tak się dzieje, wymaga zrozumienia, co robi aktualizacja rdzenia PrestaShop. Proces aktualizacji zastępuje setki plików PHP, modyfikuje tabele bazy danych, regeneruje indeksy klas, czyści cache i potencjalnie uruchamia zapytania migracyjne. Każda awaria w dowolnym punkcie tego łańcucha może pozostawić sklep w niespójnym stanie, w którym PHP napotyka błąd krytyczny, ale nie ma sposobu, aby go wyświetlić, ponieważ raportowanie błędów jest wyłączone w trybie produkcyjnym.

Najczęstsze przyczyny można podzielić na kilka kategorii: niekompatybilne moduły odwołujące się do usuniętych lub zmienionych klas rdzenia, niezgodność wersji PHP między starą a nową wersją PrestaShop, konflikty plików nadpisań (overrides), w których niestandardowe nadpisania kolidują ze zmienionymi plikami rdzenia, niewystarczające zasoby serwera powodujące przerwanie aktualizacji w trakcie procesu oraz niepowodzenia migracji bazy danych, które pozostawiają tabele w niespójnym stanie.

Krok 1: Włącz tryb debugowania

Pierwszą czynnością w przypadku białej strony jest uwidocznienie błędów. PrestaShop tłumi wyświetlanie błędów w trybie produkcyjnym, aby nie ujawniać wrażliwych informacji odwiedzającym. Musisz tymczasowo włączyć tryb debugowania, aby zobaczyć, co faktycznie idzie nie tak.

Najszybszą metodą jest edycja pliku /config/defines.inc.php. Znajdź linię definiującą _PS_MODE_DEV_ i zmień ją:

define('_PS_MODE_DEV_', true);

Jeśli nie możesz uzyskać dostępu do plików przez FTP lub SSH, ponieważ Twój panel hostingowy jest również niedostępny, niektórzy dostawcy hostingu oferują menedżer plików przez panel sterowania (cPanel, Plesk, DirectAdmin), który działa niezależnie od Twojej instalacji PrestaShop.

W PrestaShop 8.x możesz również włączyć tryb debugowania przez plik .env w katalogu głównym. Zmień APP_ENV=prod na APP_ENV=dev i ustaw APP_DEBUG=1. Aktywuje to pasek debugowania Symfony i szczegółowe strony błędów.

Po włączeniu trybu debugowania przeładuj stronę. Zamiast pustego ekranu powinieneś teraz zobaczyć szczegółowy komunikat o błędzie ze ścieżką do pliku, numerem linii i śladem stosu (stack trace). Ten komunikat o błędzie jest kluczem do diagnozy i naprawy problemu.

Krok 2: Sprawdź logi błędów

Jeśli włączenie trybu debugowania nadal pokazuje pustą stronę (co może się zdarzyć, gdy błąd występuje zanim PHP w ogóle załaduje framework PrestaShop), sprawdź logi błędów serwera bezpośrednio.

Na serwerach Apache log błędów znajduje się zazwyczaj w /var/log/apache2/error.log lub /var/log/httpd/error_log. Na Nginx z PHP-FPM sprawdź /var/log/nginx/error.log i /var/log/php-fpm/error.log (lub /var/log/php8.1-fpm.log w zależności od wersji PHP). Na hostingu współdzielonym logi błędów są zazwyczaj dostępne przez panel sterowania hostingu lub w katalogu logs na Twoim koncie hostingowym.

PrestaShop prowadzi również własne pliki logów w katalogu /var/logs/ (PrestaShop 1.7) lub /var/log/ (PrestaShop 8.x). Szukaj plików nazwanych bieżącą datą. Te logi oparte na Symfony mogą zawierać szczegółowe informacje o tym, co poszło nie tak podczas procesu aktualizacji.

Dodatkowo sprawdź katalog /log/ w głównym katalogu PrestaShop pod kątem plików logów błędów. Niektóre wersje PrestaShop zapisują tutaj krytyczne błędy, gdy nie mogą ich wyświetlić na ekranie.

Częsta przyczyna 1: Niekompatybilne moduły

Moduły są najczęstszą przyczyną białych stron po aktualizacjach. Moduł, który działał idealnie na PrestaShop 1.7.8.7, może zablokować cały sklep na wersji 1.7.8.8, jeśli korzysta z wewnętrznych klas lub metod rdzenia, które zmieniły się w aktualizacji.

Komunikat o błędzie zazwyczaj wygląda następująco: Fatal error: Class 'SomeClassName' not found lub Fatal error: Call to undefined method ClassName::methodName() lub Fatal error: Declaration of ModuleClass::hookMethod() must be compatible with CoreClass::hookMethod().

Aby to naprawić, musisz zidentyfikować i wyłączyć problematyczny moduł. Jeśli masz dostęp do back office (czasami tylko front office się zawiesza), przejdź do Modułów i wyłączaj ostatnio zainstalowane lub zaktualizowane moduły jeden po drugim, aż problem się rozwiąże.

Jeśli back office jest również niedostępne, wyłącz moduły przez bazę danych. Połącz się z bazą danych za pomocą phpMyAdmin lub klienta MySQL i wykonaj:

UPDATE ps_module SET active = 0 WHERE name = 'nazwa_problematycznego_modulu';

Jeśli nie wiesz, który moduł powoduje problem, możesz wyłączyć wszystkie moduły zewnętrzne (third-party) naraz, ustawiając ich kolumnę active na 0. Najpierw zidentyfikuj, które moduły są zewnętrzne, sprawdzając katalog /modules/ pod kątem modułów niebędących częścią PrestaShop. Następnie selektywnie je wyłączaj.

Bardziej agresywne podejście polega na zmianie nazwy katalogu modułu. Na przykład zmień nazwę /modules/somemodule/ na /modules/somemodule_disabled/. PrestaShop nie może załadować modułu, którego katalog nie odpowiada zarejestrowanej nazwie, co skutecznie go dezaktywuje bez modyfikacji bazy danych.

Częsta przyczyna 2: Niekompatybilność wersji PHP

Każda wersja PrestaShop wymaga określonego zakresu wersji PHP. PrestaShop 1.7.6 i wcześniejsze wymagają PHP 7.1 do 7.3. PrestaShop 1.7.7 do 1.7.8 obsługują PHP 7.2 do 8.0. PrestaShop 8.0 wymaga PHP 7.2 do 8.1. PrestaShop 8.1 wymaga PHP 8.0 do 8.2. PrestaShop 9.0 wymaga PHP 8.1 lub wyższego.

Jeśli Twoje środowisko hostingowe zmieniło wersję PHP podczas aktualizacji PrestaShop lub obok niej, możesz napotkać błędy składni lub wywołania przestarzałych funkcji. Typowe błędy kompatybilności PHP to: Deprecated: Function create_function() is deprecated (PHP 7.2+ z kodem pisanym dla PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ usunęło rozszerzenie mysql) oraz Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Sprawdź aktualną wersję PHP, przeglądając wynik phpinfo() lub uruchamiając php -v w wierszu poleceń. Jeśli wersja jest poza obsługiwanym zakresem dla Twojej wersji PrestaShop, przełącz się na kompatybilną wersję PHP przez panel sterowania hostingu.

Częsta przyczyna 3: Konflikty nadpisań (overrides)

System nadpisań PrestaShop pozwala modułom i programistom modyfikować zachowanie rdzenia poprzez umieszczanie zmodyfikowanych plików klas w katalogu /override/. Podczas aktualizacji klasy rdzenia się zmieniają, ale pliki nadpisań pozostają. Jeśli nadpisanie odwołuje się do sygnatury metody, która się zmieniła, właściwości, która została usunięta, lub klasy, która została przemianowana, nadpisanie powoduje błąd krytyczny.

Plik indeksu klas /var/cache/prod/class_index.php (lub /cache/class_index.php w starszych wersjach) mapuje nazwy klas do ich lokalizacji plików, w tym nadpisań. Przestarzały lub uszkodzony indeks klas może ładować nieprawidłowy plik dla klasy, powodując natychmiastowe awarie.

Aby sprawdzić, czy nadpisania są problemem, tymczasowo wyłącz system nadpisań. Edytuj /config/defines.inc.php i dodaj lub zmodyfikuj:

define('_PS_HOST_MODE_', false);

Następnie usuń plik indeksu klas, aby wymusić na PrestaShop jego regenerację bez nadpisań. Jeśli sklep załaduje się po tej zmianie, problem tkwi w jednym z Twoich plików nadpisań.

Aby zidentyfikować konkretne problematyczne nadpisanie, przejrzyj katalogi /override/classes/ i /override/controllers/. Usuwaj pliki nadpisań po jednym, kasując indeks klas po każdym usunięciu, aż znajdziesz ten powodujący awarię. Po zidentyfikowaniu albo zaktualizuj nadpisanie, aby było kompatybilne z nową wersją rdzenia, albo usuń je całkowicie, jeśli nie jest już potrzebne.

Częsta przyczyna 4: Cache i skompilowane pliki

PrestaShop generuje skompilowane szablony Smarty, cache kontenerów Symfony, mapy klas i różne inne pliki cache, które stają się nieaktualne po aktualizacji. Jeśli proces aktualizacji nie wyczyścił prawidłowo tych cache, sklep próbuje używać plików cache odwołujących się do starej struktury kodu.

Wyczyść wszystkie cache ręcznie, usuwając zawartość następujących katalogów (usuń zawartość, nie same katalogi):

/var/cache/prod/ i /var/cache/dev/ dla cache Symfony. Usuń wszystko wewnątrz tych katalogów. PrestaShop zregeneruje je przy następnym ładowaniu strony.

/cache/smarty/compile/ i /cache/smarty/cache/ dla cache szablonów Smarty. Przestarzałe skompilowane szablony są bardzo częstą przyczyną białych stron po aktualizacjach.

/var/cache/prod/class_index.php (lub /cache/class_index.php) dla mapy klas. Ten plik musi być zregenerowany po każdej aktualizacji.

W konfiguracjach PHP-FPM zresetuj również OPcache. OPcache przechowuje skompilowany bajtkod PHP w pamięci i może serwować stary kod nawet po zastąpieniu plików. Zrestartuj usługę PHP-FPM, lub jeśli nie możesz tego zrobić, utwórz mały plik PHP wywołujący opcache_reset() i otwórz go przez przeglądarkę.

Częsta przyczyna 5: Niepowodzenia migracji bazy danych

Aktualizacje PrestaShop często zawierają zmiany schematu bazy danych: nowe kolumny, zmodyfikowane indeksy, nowe tabele lub migracje danych. Jeśli proces aktualizacji został przerwany (timeout, limit pamięci, zerwanie połączenia), baza danych może znajdować się w częściowo zmigrowanym stanie.

Sprawdź bazę danych PrestaShop w tabeli ps_configuration i poszukaj wartości PS_VERSION_DB. Jeśli ta wartość nie odpowiada wersji plików na dysku, aktualizacja nie zakończyła się prawidłowo. PrestaShop może próbować ponownie uruchomić migracje przy następnym ładowaniu, lub może po prostu się zawiesić.

Niepowodzenia migracji bazy danych są najtrudniejsze do odzyskania bez kopii zapasowej. Jeśli masz kopię zapasową bazy danych sprzed aktualizacji, jej przywrócenie i ponowne uruchomienie aktualizacji jest często najbezpieczniejszą ścieżką. Jeśli nie masz kopii zapasowej, możesz być zmuszony do ręcznego zastosowania brakujących plików migracji SQL znajdujących się w katalogu /install/upgrade/sql/.

Procedura odzyskiwania krok po kroku

Postępuj zgodnie z tą sekwencją podczas odzyskiwania po białej stronie po aktualizacji rdzenia. Kolejność ma znaczenie, ponieważ każdy krok albo naprawia problem, albo eliminuje możliwą przyczynę.

Krok 1: Włącz tryb debugowania w /config/defines.inc.php, ustawiając _PS_MODE_DEV_ na true. Przeładuj stronę i przeczytaj komunikat o błędzie.

Krok 2: Usuń zawartość /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/ i /cache/smarty/cache/. Usuń class_index.php. Przeładuj stronę.

Krok 3: Jeśli błąd wskazuje na konkretny moduł, wyłącz ten moduł, zmieniając nazwę jego katalogu lub ustawiając active = 0 w tabeli ps_module bazy danych. Przeładuj stronę.

Krok 4: Jeśli błąd wskazuje na plik nadpisania, przenieś zawartość katalogu /override/ do tymczasowej lokalizacji kopii zapasowej. Ponownie usuń class_index.php. Przeładuj stronę.

Krok 5: Sprawdź, czy Twoja wersja PHP jest kompatybilna z wersją PrestaShop, do której zaktualizowałeś. Sprawdź phpinfo() lub php -v. Przełącz wersję PHP, jeśli to konieczne.

Krok 6: Sprawdź uprawnienia plików. Proces aktualizacji mógł utworzyć pliki z nieprawidłowym właścicielstwem. Wszystkie pliki PrestaShop powinny być czytelne dla użytkownika serwera WWW, a katalogi /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/ i /modules/ powinny być zapisywalne.

Krok 7: Jeśli żaden z powyższych kroków nie rozwiązuje problemu i masz kopię zapasową bazy danych, przywróć bazę danych i pliki z kopii zapasowej, a następnie ponów próbę aktualizacji po rozwiązaniu wszelkich problemów zidentyfikowanych podczas diagnostyki.

Bezpieczna procedura aktualizacji na przyszłość

Zapobieganie jest znacznie lepsze niż odzyskiwanie. Stosuj tę procedurę przy każdej aktualizacji rdzenia PrestaShop, aby zminimalizować ryzyko białych stron i utraty danych.

Przed aktualizacją: Utwórz kompletną kopię zapasową zarówno bazy danych, jak i wszystkich plików. Nie tylko bazy danych, nie tylko plików, ale obydwu. Przechowuj te kopie zapasowe w lokalizacji poza kontem hostingowym, jeśli to możliwe. Przetestuj, czy faktycznie możesz przywrócić dane z tych kopii zapasowych, zanim przejdziesz dalej.

Wyłącz wszystkie moduły zewnętrzne (third-party). To jest najskuteczniejszy pojedynczy krok, jaki możesz podjąć, aby zapobiec białym stronom. Moduły rdzenia (te dostarczane z PrestaShop) są zaprojektowane tak, aby były kompatybilne z aktualizacją, ale moduły zewnętrzne nie mają tej gwarancji. Wyłącz je przed aktualizacją i włączaj ponownie jeden po drugim potem, testując sklep po każdym ponownym włączeniu.

Wyłącz system nadpisań. Jeśli masz niestandardowe nadpisania, wyłącz je przed aktualizacją. Ponownie oceń każde nadpisanie po aktualizacji, aby określić, czy jest nadal kompatybilne i nadal potrzebne.

Przeczytaj informacje o wydaniu (release notes). Każde wydanie PrestaShop zawiera notatki o wymaganiach kompatybilności, znanych problemach i zmianach powodujących niekompatybilność. Przeczytaj je przed aktualizacją, a nie po tym, gdy coś się zepsuje.

Przełącz sklep w tryb konserwacji. Zapobiega to składaniu zamówień przez klientów podczas aktualizacji i napotykaniu błędów. Przejdź do Parametry sklepu, Ogólne, Konserwacja w back office i włącz tryb konserwacji.

Podczas aktualizacji: Monitoruj proces aktualizacji. Nie zamykaj zakładki przeglądarki ani nie przechodź na inną stronę. Jeśli aktualizacja trwa dłużej niż oczekiwano, sprawdź logi błędów serwera pod kątem błędów timeout lub pamięci. Jeśli proces wydaje się zawieszony, odczekaj co najmniej 10 minut przed podjęciem jakichkolwiek działań, ponieważ duże sklepy mogą mieć znaczące migracje bazy danych do przetworzenia.

Po aktualizacji: Wyczyść wszystkie cache. Sprawdź, czy back office ładuje się prawidłowo. Sprawdź front office. Włączaj ponownie moduły jeden po drugim, sprawdzając sklep po każdym z nich. Włącz ponownie nadpisania jeden po drugim, jeśli dotyczy. Wyłącz tryb konserwacji. Monitoruj logi błędów przez następne 24 godziny.

Strategie wycofywania zmian (rollback)

Gdy odzyskanie nie jest możliwe lub zajmuje zbyt dużo czasu, wycofanie do poprzedniej wersji może być najlepszą opcją. Jednak PrestaShop nie posiada wbudowanego mechanizmu wycofywania, więc musisz zaplanować tę ewentualność przed rozpoczęciem aktualizacji.

Pełne wycofanie z kopii zapasowej: Przywróć zarówno bazę danych, jak i pliki z kopii zapasowej sprzed aktualizacji. Jest to najczystsze podejście, ale wymaga, abyś wykonał kompletną kopię zapasową przed aktualizacją. Po przywróceniu sprawdź, czy sklep działa prawidłowo i czy żadne zamówienia ani dane klientów utworzone podczas nieudanego okresu aktualizacji nie zostały utracone (jeśli sklep był w trybie konserwacji, nic nie powinno się zmienić).

Częściowe wycofanie plików: Jeśli uszkodzone są tylko pliki, a baza danych jest w porządku, możesz zastąpić pliki PrestaShop poprzednią wersją, zachowując aktualną bazę danych. Pobierz dokładną poprzednią wersję PrestaShop z oficjalnego archiwum wydań, rozpakuj ją i nadpisz pliki na serwerze. Zachowaj swoje niestandardowe moduły, motywy i pliki konfiguracyjne. To podejście jest ryzykowne, ponieważ baza danych mogła zostać częściowo zmigrowana, tworząc niespójność między plikami a schematem bazy danych.

Naprawa do przodu (forward fix): Czasami najszybszą ścieżką nie jest wycofanie, ale naprawienie konkretnego błędu. Jeśli błąd jest spowodowany pojedynczym niekompatybilnym modułem lub nadpisaniem, naprawienie lub usunięcie tego jednego komponentu może zająć minuty w porównaniu do godzin potrzebnych na pełne wycofanie. To podejście jest najlepsze, gdy wyraźnie zidentyfikowałeś przyczynę z komunikatu o błędzie.

Znaczenie kopii zapasowych bazy danych

Każda sekcja tego przewodnika wspomina o kopiach zapasowych i nie bez powodu. Baza danych PrestaShop zawiera każdy produkt, każde zamówienie, każde konto klienta, każde ustawienie konfiguracji i każdą treść w Twoim sklepie. Jej utrata oznacza utratę danych biznesowych.

Automatyczne codzienne kopie zapasowe nie są opcjonalne dla produkcyjnego sklepu PrestaShop. Skonfiguruj system kopii zapasowych swojego dostawcy hostingu, użyj modułu do tworzenia kopii zapasowych bazy danych lub ustaw zadanie cron uruchamiające mysqldump w regularnych odstępach czasu. Przechowuj kopie zapasowe w wielu lokalizacjach. Okresowo testuj procedurę przywracania, aby upewnić się, że kopie zapasowe są faktycznie użyteczne.

Przed każdą aktualizacją utwórz ręczną kopię zapasową oprócz automatycznych kopii zapasowych. Nazwij ją wyraźnie z datą i wersją PrestaShop, abyś mógł natychmiast ją zidentyfikować w razie potrzeby przywrócenia.

Kiedy szukać profesjonalnej pomocy

Jeśli wykonałeś wszystkie kroki z tego przewodnika i nadal widzisz białą stronę, lub jeśli komunikaty o błędach wskazują na głębokie problemy rdzenia wymagające napraw na poziomie kodu, może nadszedł czas, aby zaangażować programistę PrestaShop. Przekaż mu zebrane komunikaty o błędach, wersje PrestaShop (przed i po aktualizacji), wersję PHP oraz wszelkie działania, które już podjąłeś. Te informacje znacząco skrócą czas potrzebny na diagnozę i rozwiązanie problemu.

Próby ręcznej edycji plików rdzenia PrestaShop bez zrozumienia architektury frameworka mogą stworzyć dodatkowe problemy. Jeśli komunikat o błędzie odnosi się do kontenerów Symfony, wstrzykiwania zależności (dependency injection) lub konfiguracji kernela, są to obszary, w których nieprawidłowe zmiany mogą kaskadowo prowadzić do wielu awarii.