# Optymalizator Obrazów WebP i AVIF: kompletny przewodnik
> Prezentacja Optymalizator obrazów WebP i AVIF konwertuje i kompresuje obrazy Twojego sklepu bezpośrednio na Twoim serwerze, a następnie automatycznie serwuje każdemu odwiedzającemu najlżejszy format, który jego przeglądarka potrafi wyświetlić. Cała…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-01
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafireflyimageoptimizer/index.md), [en](https://www.datafirefly.com/en/documentation/datafireflyimageoptimizer/index.md), [es](https://www.datafirefly.com/es/documentation/datafireflyimageoptimizer/index.md), [de](https://www.datafirefly.com/de/documentation/datafireflyimageoptimizer/index.md), [it](https://www.datafirefly.com/it/documentation/datafireflyimageoptimizer/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafireflyimageoptimizer/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafireflyimageoptimizer/index.md)
- Indeks:
## Prezentacja
Optymalizator obrazów WebP i AVIF konwertuje i kompresuje obrazy Twojego sklepu bezpośrednio na Twoim serwerze, a następnie automatycznie serwuje każdemu odwiedzającemu najlżejszy format, który jego przeglądarka potrafi wyświetlić. Cała konwersja jest lokalna: żaden obraz nie jest wysyłany do usługi zewnętrznej, nie ma limitów ani kredytów.
Kluczowy punkt: Twoje oryginalne pliki nigdy nie są nadpisywane. Dla każdego obrazu `produkt.jpg` moduł generuje `produkt.jpg.webp` i `produkt.jpg.avif` obok oryginału, a następnie serwuje je wyłącznie zgodnym przeglądarkom. Operacja jest więc w pełni odwracalna. Moduł jest zgodny z PrestaShop 1.7.6, 8 i 9 oraz działa z Imagick, GD lub binariami `cwebp` i `avifenc`.
## Wymagania i zgodność
- **PrestaShop**: 1.7.6 do 9.x, także w multisklepie.
- **PHP**: 7.2 do 8.3.
- **Co najmniej jeden silnik obrazów**: rozszerzenie **Imagick** (zalecane, skompilowane ze wsparciem WebP/AVIF), rozszerzenie **GD** ze wsparciem WebP/AVIF lub binaria systemowe `cwebp` i `avifenc`.
- **Serwer WWW**: Apache (przezroczyste dostarczanie `.htaccess`) lub Nginx (tryb `picture`).
Nie wiesz, co obsługuje Twój serwer? Moduł zawiera przycisk **Testuj silniki**, który konwertuje przykładowy obraz i wskazuje, format po formacie, który silnik jest dostępny i jaką wagę produkuje.
## Instalacja
1. W zapleczu otwórz **Moduły > Menedżer modułów**.
2. Kliknij **Zainstaluj moduł** i wgraj archiwum ZIP modułu.
3. Po zakończeniu instalacji kliknij **Konfiguruj**.
Podczas instalacji moduł tworzy swoje dwie tabele (statystyki i kolejka), rejestruje hooki, stosuje gotowe ustawienia domyślne i, jeśli tryb dostarczania `.htaccess` jest aktywny, zapisuje swój blok reguł w katalogu `/img`. Sprawdzana jest obecność co najmniej jednej biblioteki obrazów (GD lub Imagick): jeśli żadna nie jest dostępna, instalacja jest przerywana z czytelnym komunikatem.
## Pierwsze kroki
Wystarczą trzy kroki, aby zoptymalizować cały istniejący katalog:
1. **Przetestuj silniki**: na stronie konfiguracji kliknij _Testuj silniki_, aby potwierdzić, że WebP i AVIF mogą być generowane.
2. **Przeanalizuj mediatekę**: kliknij _Analizuj mediatekę_: moduł przechodzi przez katalogi docelowe i wypełnia kolejkę obrazami do przetworzenia.
3. **Uruchom konwersję**: kliknij _Uruchom konwersję_: przetwarzanie odbywa się partiami, z paskiem postępu, i można je w każdej chwili wstrzymać oraz wznowić.
Nowe obrazy dodane później w zapleczu są konwertowane automatycznie (zobacz _Automatyczna konwersja przy uploadzie_).
## Konfiguracja
Strona konfiguracji łączy pulpit (możliwości serwera i uzyskane oszczędności), narzędzie przetwarzania masowego, formularz ustawień i panel konserwacji.
### Formaty next-gen
- **Generuj WebP**: włącza tworzenie plików `.webp`.
- **Jakość WebP**: od 1 do 100. Zakres 80–85 daje najlepszy kompromis jakości i wagi.
- **Generuj AVIF**: włącza tworzenie plików `.avif`.
- **Jakość AVIF**: AVIF jest gęstszy niż WebP: wartość od 45 do 55 zwykle wystarcza dla doskonałej jakości.
### Silnik i dostarczanie
- **Silnik konwersji**: _Automatyczny_ (zalecany), _Imagick_, _GD_ lub _Binaria_. W trybie automatycznym moduł wybiera najlepszy dostępny silnik dla każdego formatu, w kolejności Imagick, potem GD, potem binaria.
- **Tryb dostarczania**: _.htaccess_ (przezroczysta negocjacja Apache), _picture_ (przepisywanie HTML dla Nginx) lub _brak_. Na Apache zostaw `.htaccess`: nie trzeba robić nic więcej. Na Nginx wybierz `picture`.
### Odłożone ładowanie (lazy-load)
- **Natywny lazy-load**: dodaje `loading="lazy"` i `decoding="async"` do obrazów, bez JavaScriptu i bez wpływu na SEO.
- **Efekt przenikania**: delikatny kosmetyczny efekt przy pojawianiu się obrazu (opcjonalny).
### Kompresja oryginałów
- **Rekompresuj oryginały**: ponownie zapisuje oryginalne JPEG/PNG w wersji zoptymalizowanej. Kopia zapasowa `.dforig` jest zachowywana, aby umożliwić przywrócenie.
- **Jakość JPEG (oryginały)**: jakość stosowana przy rekompresji oryginalnych JPEG.
Rekompresja oryginałów jest opcjonalna i domyślnie wyłączona. Konwersja WebP/AVIF daje już zasadniczy zysk; włącz rekompresję tylko wtedy, gdy chcesz również odchudzić pliki serwowane starym przeglądarkom.
### Zakres
- **Typy obrazów do przetworzenia**: produkty, kategorie, producenci, dostawcy, sklepy i strony CMS. Typy faktycznie dostępne na Twojej instalacji są wykrywane automatycznie.
- **Obrazy motywu**: przetwarza również katalog `assets/img` Twojego motywu (i zarządza tam dedykowanym `.htaccess` przy dostarczaniu Apache).
- **Wyklucz**: jeden wzorzec na linię: każda ścieżka zawierająca jeden z tych fragmentów jest ignorowana (na przykład `logo` lub `/img/cms/banner`).
### Zaawansowane
- **Automatyczna konwersja przy uploadzie**: konwertuje każdy obraz produktu od razu przy jego (re)generacji w zapleczu.
- **Ignoruj animowane obrazy**: animowane GIF-y i PNG (APNG) są wykrywane i pozostawiane bez zmian.
- **Minimalny rozmiar (bajty)**: poniżej tej wagi obraz jest ignorowany: bardzo małe obrazy nic nie zyskują na konwersji.
- **Rozmiar partii**: liczba obrazów przetwarzanych na żądanie AJAX lub przebieg crona. Na hostingu współdzielonym zalecane 10 do 30.
Po każdej zmianie pamiętaj o **zapisaniu**. Jeśli zmienisz tryb dostarczania, blok `.htaccess` jest odpowiednio dodawany lub usuwany automatycznie.
## Jak działa dostarczanie
Moduł jedynie _generuje_ pliki next-gen i wskazuje serwerowi, jak je _serwować_. Adresy URL Twoich obrazów nigdy się nie zmieniają.
### Tryb .htaccess (Apache)
Moduł zapisuje blok reguł w `/img/.htaccess`. Gdy przeglądarka żąda `produkt.jpg`, serwer odczytuje nagłówek `Accept`: jeśli deklaruje wsparcie AVIF i istnieje `produkt.jpg.avif`, zwracany jest ten plik; w przeciwnym razie próbowany jest WebP, a w ostateczności oryginalny JPEG. Dodawany jest nagłówek `Vary: Accept`, aby cache i CDN-y przechowywały właściwą wersję per przeglądarka. Wszystko jest przezroczyste: Twój motyw nie jest modyfikowany i nic się nie psuje po wyłączeniu modułu.
Blok jest zapisywany w `/img/.htaccess`, a nie w katalogu głównym, ponieważ PrestaShop regularnie regeneruje swój główny `.htaccess`. Katalog `/img` nie jest zarządzany przez PrestaShop: blok pozostaje tam stabilny.
### Tryb picture (Nginx)
Na serwerach Nginx negocjacja przez `.htaccess` nie jest dostępna. Tryb `picture` przepisuje wówczas znaczniki `img` strony na `picture` ze źródłami AVIF i WebP, tuż przed wysłaniem strony. Przeglądarka sama wybiera pierwsze źródło, które potrafi wyświetlić.
## Optymalizacja dużego katalogu (CRON i CLI)
Narzędzie przetwarzania masowego w AJAX wystarcza większości sklepów. Dla tysięcy obrazów lub do automatycznej obsługi nowych obrazów użyj crona lub linii poleceń.
### Zadanie CRON
Zaplanuj regularne żądanie na adres URL wyświetlany w panelu _Automatyzacja_ konfiguracji. Jest zabezpieczony tokenem:
```
https://twoj-sklep.pl/index.php?fc=module&module=datafireflyimageoptimizer&controller=cron&token=TWOJ_TOKEN&scan=1&limit=200
```
Parametr `scan=1` uruchamia ponowną analizę przed przetwarzaniem (przydatne do wykrywania nowych obrazów), a `limit` określa liczbę obrazów przetwarzanych na przebieg.
### Polecenie CLI
Dla bardzo dużych mediatek polecenie w linii komend przetwarza kolejkę w tle, bez timeoutu:
```
php modules/datafireflyimageoptimizer/cli/optimize.php --scan --loop
```
Dostępne opcje: `--scan` (analizuj przed przetwarzaniem), `--loop` (kontynuuj aż do opróżnienia kolejki), `--limit=N` (rozmiar partii), `--types=products,categories` (ogranicz cele dla tego wykonania), `--force` (wymuś ponowną konwersję nawet jeśli pliki next-gen są aktualne) i `--quiet` (minimalny output).
## Przywracanie i odwracalność
Ponieważ oryginały nigdy nie są nadpisywane, możesz się wycofać w każdej chwili. W panelu _Konserwacja_ przycisk **Przywróć wszystko** usuwa wygenerowane pliki `.webp` i `.avif`, przywraca rekompresowane oryginały z ich kopii zapasowej `.dforig`, usuwa blok `.htaccess` i czyści statystyki. Ten sam panel pozwala też w razie potrzeby **zregenerować .htaccess**.
Wbudowane zabezpieczenie: jeśli wersja next-gen okaże się cięższa od oryginału (zdarza się to przy niektórych już mocno skompresowanych obrazach), jest automatycznie odrzucana. Przeglądarka otrzymuje wtedy plik oryginalny.
## Odinstalowanie
Odinstalowanie usuwa blok `.htaccess`, tabele i konfigurację modułu. Już wygenerowane pliki `.webp` i `.avif` pozostają na dysku. Aby wrócić do czystej mediateki, użyj najpierw **Przywróć wszystko** w zakładce Konserwacja, a potem odinstaluj moduł.
## Rozwiązywanie problemów
**Obrazy next-gen nie są serwowane.** W trybie Apache sprawdź, czy `mod_rewrite` i `mod_headers` są aktywne oraz czy pliki `.htaccess` są uwzględniane (dyrektywa `AllowOverride`). Potwierdź także, w narzędziach przeglądarki, że żądanie obrazu zwraca typ `image/avif` lub `image/webp`.
- **Test silników nie przechodzi dla AVIF**: Twój Imagick/GD prawdopodobnie nie jest skompilowany ze wsparciem AVIF. Zainstaluj binaria `avifenc` albo wyłącz AVIF i zostaw WebP.
- **Biała strona na froncie po aktywacji**: zwykle wiąże się z trybem `picture` na mocno spersonalizowanym motywie. Wróć do trybu `.htaccess` (Apache) lub _brak_, a następnie skontaktuj się ze wsparciem.
- **Konwersja jest wolna**: zmniejsz _rozmiar partii_ albo przenieś przetwarzanie na crona lub CLI, zaprojektowane dla dużych wolumenów.
- **Niektóre obrazy nie są konwertowane**: sprawdź, czy przekraczają _minimalny rozmiar_, czy nie są animowane (jeśli opcja jest aktywna) i czy nie dotyczy ich żaden wzorzec _wykluczenia_.
## FAQ
### Czy moje obrazy są wysyłane do usługi zewnętrznej?
Nie. Cała konwersja jest w 100% lokalna, na Twoim serwerze. Żaden obraz nie jest przekazywany podmiotom trzecim, nie ma limitów ani kredytów.
### Czy moje oryginalne pliki są modyfikowane?
Domyślnie nie: wersje WebP i AVIF są tworzone obok oryginału. Jeśli włączysz rekompresję oryginałów, zachowywana jest kopia zapasowa `.dforig`, która pozwala je przywrócić.
### Czy muszę modyfikować motyw lub serwer?
W trybie Apache nie: blok `.htaccess` zajmuje się wszystkim. Na Nginx po prostu włącz tryb `picture` w ustawieniach.
### Jakie formaty są obsługiwane?
Moduł generuje WebP i AVIF z Twoich plików JPEG, PNG i GIF (nieanimowanych).
### Czy jest zgodny z PrestaShop 9 i multisklepem?
Tak, moduł jest zgodny z PrestaShop 1.7.6 do 9.x i działa w kontekście multisklepowym. Używa wyłącznie oficjalnych hooków.
### Jak przetworzyć katalog z tysiącami obrazów?
Uruchom analizę, potem konwersję partiami w AJAX, albo zaplanuj zadanie CRON lub polecenie CLI, które przetwarzają kolejkę w tle bez timeoutu.