# Ottimizzatore di immagini WebP e AVIF — Guida completa

> Panoramica L'Ottimizzatore di immagini WebP e AVIF converte e comprime le immagini del tuo negozio direttamente sul tuo server, poi serve automaticamente a ogni visitatore il formato più leggero che…

- Pagina: <https://www.datafirefly.com/it/documentation/datafireflyimageoptimizer/>
- Lingua: it
- Aggiornato il: 2026-06-27
- Altre lingue: [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), [pl](https://www.datafirefly.com/pl/documentation/datafireflyimageoptimizer/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafireflyimageoptimizer/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafireflyimageoptimizer/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## Panoramica

L'Ottimizzatore di immagini WebP e AVIF converte e comprime le immagini del tuo negozio direttamente sul tuo server, poi serve automaticamente a ogni visitatore il formato più leggero che il suo browser è in grado di mostrare. Tutta la conversione è locale: nessuna immagine viene inviata a un servizio di terze parti e non ci sono quote o crediti.

Punto essenziale: i tuoi file originali non vengono mai sovrascritti. Per ogni immagine `prodotto.jpg`, il modulo genera `prodotto.jpg.webp` e `prodotto.jpg.avif` accanto all'originale, poi li serve solo ai browser compatibili. L'operazione è quindi completamente reversibile. Il modulo è compatibile con PrestaShop 1.7.6, 8 e 9 e funziona con Imagick, GD o i binari `cwebp` e `avifenc`.

## Requisiti e compatibilità

- **PrestaShop** — da 1.7.6 a 9.x, incluso il multinegozio.
- **PHP** — da 7.2 a 8.3.
- **Almeno un motore di immagine** — l'estensione **Imagick** (consigliata, compilata con il supporto WebP/AVIF), o l'estensione **GD** con il supporto WebP/AVIF, o i binari di sistema `cwebp` e `avifenc`.
- **Server web** — Apache (consegna `.htaccess` trasparente) o Nginx (modalità `picture`).

Non sei sicuro di ciò che il tuo server supporta? Il modulo include un pulsante **Testa i motori** che converte un'immagine di esempio e ti indica, formato per formato, quale motore è disponibile e quale peso produce.

## Installazione

1. Dal back office, apri **Moduli > Gestore dei moduli**.
2. Clicca su **Carica un modulo** e trascina l'archivio ZIP del modulo.
3. Una volta completata l'installazione, clicca su **Configura**.

All'installazione, il modulo crea le sue due tabelle (statistiche e coda), registra i suoi hook, applica delle impostazioni predefinite pronte all'uso e, se la modalità di consegna `.htaccess` è attiva, scrive il suo blocco di regole nella cartella `/img`. Viene verificata la presenza di almeno una libreria di immagini (GD o Imagick): se nessuna è disponibile, l'installazione viene interrotta con un messaggio esplicito.

## Primi passi

Bastano tre passaggi per ottimizzare tutto il tuo catalogo esistente:

1. **Testa i motori** — nella pagina di configurazione, clicca su _Testa i motori_ per confermare che WebP e AVIF possono essere prodotti.
2. **Analizza la libreria multimediale** — clicca su _Analizza la libreria multimediale_: il modulo percorre le cartelle di destinazione e riempie la coda con le immagini da elaborare.
3. **Avvia la conversione** — clicca su _Avvia la conversione_: l'elaborazione avviene in lotti, con una barra di avanzamento, e può essere messa in pausa e ripresa in qualsiasi momento.

Le nuove immagini aggiunte successivamente nel back office vengono convertite automaticamente (vedi _Conversione automatica al caricamento_).

## Configurazione

La pagina di configurazione riunisce un cruscotto (capacità del server ed economie realizzate), lo strumento di elaborazione in batch, il modulo di impostazioni e un pannello di manutenzione.

### Formati next-gen

- **Genera WebP** — attiva la creazione dei file `.webp`.
- **Qualità WebP** — da 1 a 100. L'intervallo 80–85 offre il miglior compromesso qualità/peso.
- **Genera AVIF** — attiva la creazione dei file `.avif`.
- **Qualità AVIF** — l'AVIF è più denso del WebP: un valore da 45 a 55 è generalmente sufficiente per un'ottima qualità.

### Motore e consegna

- **Motore di conversione** — _Automatico_ (consigliato), _Imagick_, _GD_ o _Binari_. In modalità automatica, il modulo sceglie il miglior motore disponibile per ogni formato, nell'ordine Imagick, poi GD, poi binari.
- **Modalità di consegna** — _.htaccess_ (negoziazione trasparente di Apache), _picture_ (riscrittura HTML per Nginx) o _nessuna_. Su Apache, lascia `.htaccess`: non c'è altro da fare. Su Nginx, scegli `picture`.

### Caricamento differito (lazy-load)

- **Lazy-load nativo** — aggiunge `loading="lazy"` e `decoding="async"` alle immagini, senza JavaScript e senza impatto sulla SEO.
- **Effetto dissolvenza** — una leggera dissolvenza cosmetica alla comparsa dell'immagine (opzionale).

### Compressione degli originali

- **Ricomprimi gli originali** — risalva i file JPEG/PNG originali in una versione ottimizzata. Viene conservato un backup `.dforig` per consentire il ripristino.
- **Qualità JPEG (originali)** — la qualità applicata durante la ricompressione dei JPEG originali.

La ricompressione degli originali è facoltativa e disattivata per impostazione predefinita. La conversione WebP/AVIF apporta già la maggior parte del guadagno; attiva la ricompressione solo se vuoi anche alleggerire i file serviti ai browser più datati.

### Ambito

- **Tipi di immagini da elaborare** — prodotti, categorie, produttori, fornitori, negozi e pagine CMS. I tipi realmente disponibili sulla tua installazione vengono rilevati automaticamente.
- **Immagini del tema** — elabora anche la cartella `assets/img` del tuo tema (e vi gestisce un `.htaccess` dedicato con la consegna Apache).
- **Escludi** — un pattern per riga: qualsiasi percorso che contiene uno di questi frammenti viene ignorato (per esempio `logo` o `/img/cms/banner`).

### Avanzate

- **Conversione automatica al caricamento** — converte ogni immagine prodotto non appena viene (ri)generata nel back office.
- **Ignora le immagini animate** — le GIF e i PNG animati (APNG) vengono rilevati e lasciati intatti.
- **Dimensione minima (byte)** — al di sotto di questo peso, l'immagine viene ignorata: le immagini molto piccole non guadagnano nulla a essere convertite.
- **Dimensione dei lotti** — il numero di immagini elaborate per richiesta AJAX o per passaggio del cron. Si consiglia da 10 a 30 su hosting condiviso.

Dopo ogni modifica, ricorda di **salvare**. Se cambi la modalità di consegna, il blocco `.htaccess` viene aggiunto o rimosso automaticamente di conseguenza.

## Come funziona la consegna

Il modulo si limita a _generare_ i file next-gen e a indicare al server come _servirli_. Gli URL delle tue immagini non cambiano mai.

### Modalità .htaccess (Apache)

Il modulo scrive un blocco di regole in `/img/.htaccess`. Quando un browser richiede `prodotto.jpg`, il server legge l'header `Accept`: se annuncia il supporto dell'AVIF ed esiste `prodotto.jpg.avif`, viene restituito quel file; altrimenti viene tentato il WebP, poi in alternativa il JPEG originale. Viene aggiunto un header `Vary: Accept` affinché le cache e i CDN conservino la versione corretta per browser. Tutto è trasparente: il tuo tema non viene modificato e nulla si rompe se disattivi il modulo.

Il blocco viene scritto in `/img/.htaccess` e non nella radice, perché PrestaShop rigenera regolarmente il suo `.htaccess` radice. La cartella `/img`, invece, non è gestita da PrestaShop: il blocco rimane stabile lì.

### Modalità picture (Nginx)

Sui server Nginx, la negoziazione tramite `.htaccess` non è disponibile. La modalità `picture` riscrive allora i tag `img` della pagina in `picture` con sorgenti AVIF e WebP, appena prima dell'invio della pagina. Il browser sceglie da solo la prima sorgente che sa mostrare.

## Ottimizzare un catalogo di grandi dimensioni (CRON e CLI)

Lo strumento di elaborazione in batch via AJAX va bene per la maggior parte dei negozi. Per migliaia di immagini o per automatizzare la gestione delle nuove immagini, usa il cron o la riga di comando.

### Attività CRON

Pianifica una richiesta regolare verso l'URL mostrato nel pannello _Automazione_ della configurazione. È protetta da un token:

```
https://il-tuo-negozio/index.php?fc=module&module=datafireflyimageoptimizer&controller=cron&token=IL_TUO_TOKEN&scan=1&limit=200
```

Il parametro `scan=1` avvia un'analisi prima dell'elaborazione (utile per rilevare nuove immagini) e `limit` fissa il numero di immagini elaborate per passaggio.

### Comando CLI

Per le librerie multimediali molto grandi, la riga di comando elabora la coda in background, senza timeout:

```
php modules/datafireflyimageoptimizer/cli/optimize.php --scan --loop
```

Opzioni disponibili: `--scan` (analizzare prima di elaborare), `--loop` (continuare fino a svuotare la coda), `--limit=N` (dimensione dei lotti), `--types=products,categories` (limitare le destinazioni per questa esecuzione), `--force` (forzare la riconversione anche se i file next-gen sono aggiornati) e `--quiet` (output minimo).

## Ripristino e reversibilità

Poiché gli originali non vengono mai sovrascritti, puoi tornare indietro in qualsiasi momento. Nel pannello _Manutenzione_, il pulsante **Ripristina tutto** elimina i file `.webp` e `.avif` generati, ripristina gli originali ricompressi dal loro backup `.dforig`, rimuove il blocco `.htaccess` e svuota le statistiche. Lo stesso pannello consente anche di **rigenerare il .htaccess** se necessario.

Sicurezza integrata: se una versione next-gen risulta più pesante dell'originale (capita su alcune immagini già molto compresse), viene scartata automaticamente. Il browser riceve allora il file originale.

## Disinstallazione

La disinstallazione rimuove il blocco `.htaccess`, elimina le tabelle e la configurazione del modulo. I file `.webp` e `.avif` già generati restano sul disco. Per ripartire da una libreria multimediale pulita, usa prima **Ripristina tutto** nella scheda Manutenzione, poi disinstalla il modulo.

## Risoluzione dei problemi

**Le immagini next-gen non vengono servite.** In modalità Apache, verifica che `mod_rewrite` e `mod_headers` siano attivi e che i file `.htaccess` vengano presi in considerazione (direttiva `AllowOverride`). Conferma anche, con gli strumenti del tuo browser, che la richiesta dell'immagine restituisca effettivamente un tipo `image/avif` o `image/webp`.

- **Il test dei motori fallisce per l'AVIF** — il tuo Imagick/GD probabilmente non è compilato con il supporto AVIF. Installa i binari `avifenc`, oppure disattiva l'AVIF e conserva il WebP.
- **Pagina bianca sul front dopo l'attivazione** — è generalmente legato alla modalità `picture` su un tema molto personalizzato. Torna alla modalità `.htaccess` (Apache) o _nessuna_, poi contatta il supporto.
- **La conversione è lenta** — riduci la _dimensione dei lotti_, oppure sposta l'elaborazione sul cron o sulla CLI, progettati per i grandi volumi.
- **Alcune immagini non vengono convertite** — verifica che superino la _dimensione minima_, che non siano animate (se l'opzione è attiva) e che nessun pattern di _esclusione_ le riguardi.

## FAQ

### Le mie immagini vengono inviate a un servizio esterno?

No. Tutta la conversione è 100% locale, sul tuo server. Nessuna immagine viene trasmessa a terzi e non ci sono quote o crediti.

### I miei file originali vengono modificati?

Non per impostazione predefinita: le versioni WebP e AVIF vengono create accanto all'originale. Se attivi la ricompressione degli originali, viene conservato un backup `.dforig` per ripristinarli.

### Devo modificare il mio tema o il mio server?

In modalità Apache, no: il blocco `.htaccess` si occupa di tutto. Su Nginx, attiva semplicemente la modalità `picture` nelle impostazioni.

### Quali formati sono supportati?

Il modulo genera WebP e AVIF dai tuoi file JPEG, PNG e GIF (non animati).

### È compatibile con PrestaShop 9 e con il multinegozio?

Sì, il modulo è compatibile con PrestaShop 1.7.6 a 9.x e funziona in contesto multinegozio. Utilizza esclusivamente hook ufficiali.

### Come elaboro un catalogo di diverse migliaia di immagini?

Avvia l'analisi e poi la conversione in batch via AJAX, oppure pianifica l'attività CRON o il comando CLI, che elaborano la coda in background senza timeout.