# Optimizador de imágenes WebP y AVIF — Guía completa

> Presentación El Optimizador de imágenes WebP y AVIF convierte y comprime las imágenes de tu tienda directamente en tu servidor, y después sirve automáticamente a cada visitante el formato más…

- Página: <https://www.datafirefly.com/es/documentation/datafireflyimageoptimizer/>
- Idioma: es
- Actualizado el: 2026-06-27
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/datafireflyimageoptimizer/index.md), [en](https://www.datafirefly.com/en/documentation/datafireflyimageoptimizer/index.md), [de](https://www.datafirefly.com/de/documentation/datafireflyimageoptimizer/index.md), [it](https://www.datafirefly.com/it/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)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## Presentación

El Optimizador de imágenes WebP y AVIF convierte y comprime las imágenes de tu tienda directamente en tu servidor, y después sirve automáticamente a cada visitante el formato más ligero que su navegador puede mostrar. Toda la conversión es local: ninguna imagen se envía a un servicio de terceros y no hay cuotas ni créditos.

Punto esencial: tus archivos originales nunca se sobrescriben. Para cada imagen `producto.jpg`, el módulo genera `producto.jpg.webp` y `producto.jpg.avif` junto al original, y los sirve solo a los navegadores compatibles. La operación es, por tanto, totalmente reversible. El módulo es compatible con PrestaShop 1.7.6, 8 y 9, y funciona con Imagick, GD o los binarios `cwebp` y `avifenc`.

## Requisitos y compatibilidad

- **PrestaShop** — 1.7.6 a 9.x, incluido multitienda.
- **PHP** — 7.2 a 8.3.
- **Al menos un motor de imagen** — la extensión **Imagick** (recomendada, compilada con soporte WebP/AVIF), o la extensión **GD** con soporte WebP/AVIF, o los binarios del sistema `cwebp` y `avifenc`.
- **Servidor web** — Apache (entrega `.htaccess` transparente) o Nginx (modo `picture`).

¿No estás seguro de lo que admite tu servidor? El módulo incluye un botón **Probar los motores** que convierte una imagen de ejemplo y te indica, formato por formato, qué motor está disponible y qué tamaño produce.

## Instalación

1. Desde el back office, abre **Módulos > Gestor de módulos**.
2. Haz clic en **Subir un módulo** y suelta el archivo ZIP del módulo.
3. Una vez completada la instalación, haz clic en **Configurar**.

En la instalación, el módulo crea sus dos tablas (estadísticas y cola), registra sus hooks, aplica unos ajustes por defecto listos para usar y, si el modo de entrega `.htaccess` está activo, escribe su bloque de reglas en la carpeta `/img`. Se comprueba la presencia de al menos una librería de imagen (GD o Imagick): si no hay ninguna disponible, la instalación se interrumpe con un mensaje explícito.

## Primeros pasos

Tres pasos bastan para optimizar todo tu catálogo existente:

1. **Prueba los motores** — en la página de configuración, haz clic en _Probar los motores_ para confirmar que se pueden producir WebP y AVIF.
2. **Analiza la biblioteca multimedia** — haz clic en _Analizar la biblioteca multimedia_: el módulo recorre las carpetas de destino y llena la cola con las imágenes a procesar.
3. **Inicia la conversión** — haz clic en _Iniciar la conversión_: el procesamiento se realiza por lotes, con una barra de progreso, y se puede pausar y reanudar en cualquier momento.

Las nuevas imágenes añadidas después en el back office se convierten automáticamente (consulta _Conversión automática al subir_).

## Configuración

La página de configuración reúne un panel (capacidades del servidor y ahorros conseguidos), la herramienta de procesamiento por lotes, el formulario de ajustes y un panel de mantenimiento.

### Formatos next-gen

- **Generar WebP** — activa la creación de los archivos `.webp`.
- **Calidad WebP** — de 1 a 100. El rango 80–85 ofrece el mejor equilibrio calidad/tamaño.
- **Generar AVIF** — activa la creación de los archivos `.avif`.
- **Calidad AVIF** — AVIF es más denso que WebP: un valor de 45 a 55 suele bastar para una calidad excelente.

### Motor y entrega

- **Motor de conversión** — _Automático_ (recomendado), _Imagick_, _GD_ o _Binarios_. En modo automático, el módulo elige el mejor motor disponible para cada formato, en el orden Imagick, luego GD y luego binarios.
- **Modo de entrega** — _.htaccess_ (negociación transparente de Apache), _picture_ (reescritura HTML para Nginx) o _ninguno_. En Apache, deja `.htaccess`: no hay nada más que hacer. En Nginx, elige `picture`.

### Carga diferida (lazy-load)

- **Lazy-load nativo** — añade `loading="lazy"` y `decoding="async"` a las imágenes, sin JavaScript y sin impacto en el SEO.
- **Efecto de fundido** — un ligero fundido cosmético al aparecer la imagen (opcional).

### Compresión de los originales

- **Recomprimir los originales** — vuelve a guardar los JPEG/PNG originales en una versión optimizada. Se conserva una copia `.dforig` para permitir la restauración.
- **Calidad JPEG (originales)** — la calidad aplicada al recomprimir los JPEG originales.

La recompresión de los originales es opcional y está desactivada por defecto. La conversión WebP/AVIF ya aporta la mayor parte de la ganancia; activa la recompresión solo si también quieres aligerar los archivos servidos a los navegadores antiguos.

### Ámbito

- **Tipos de imágenes a procesar** — productos, categorías, fabricantes, proveedores, tiendas y páginas CMS. Los tipos realmente disponibles en tu instalación se detectan automáticamente.
- **Imágenes del tema** — procesa también la carpeta `assets/img` de tu tema (y gestiona allí un `.htaccess` dedicado con la entrega Apache).
- **Excluir** — un patrón por línea: se omite cualquier ruta que contenga uno de estos fragmentos (por ejemplo `logo` o `/img/cms/banner`).

### Avanzado

- **Conversión automática al subir** — convierte cada imagen de producto en cuanto se (re)genera en el back office.
- **Omitir las imágenes animadas** — los GIF y PNG animados (APNG) se detectan y se dejan intactos.
- **Tamaño mínimo (bytes)** — por debajo de este tamaño, la imagen se omite: las imágenes muy pequeñas no ganan nada al convertirse.
- **Tamaño de los lotes** — el número de imágenes procesadas por petición AJAX o por pasada de cron. Se recomienda de 10 a 30 en alojamiento compartido.

Después de cada cambio, recuerda **guardar**. Si cambias el modo de entrega, el bloque `.htaccess` se añade o se retira automáticamente en consecuencia.

## Cómo funciona la entrega

El módulo solo _genera_ los archivos next-gen e indica al servidor cómo _servirlos_. Las URLs de tus imágenes nunca cambian.

### Modo .htaccess (Apache)

El módulo escribe un bloque de reglas en `/img/.htaccess`. Cuando un navegador solicita `producto.jpg`, el servidor lee el encabezado `Accept`: si anuncia soporte de AVIF y existe `producto.jpg.avif`, se devuelve ese archivo; si no, se intenta el WebP, y por último el JPEG original como alternativa. Se añade un encabezado `Vary: Accept` para que las cachés y los CDN conserven la versión correcta por navegador. Todo es transparente: tu tema no se modifica y nada se rompe si desactivas el módulo.

El bloque se escribe en `/img/.htaccess` y no en la raíz, porque PrestaShop regenera con regularidad su `.htaccess` raíz. La carpeta `/img`, en cambio, no la gestiona PrestaShop: el bloque permanece estable allí.

### Modo picture (Nginx)

En los servidores Nginx, la negociación por `.htaccess` no está disponible. El modo `picture` reescribe entonces las etiquetas `img` de la página en `picture` con fuentes AVIF y WebP, justo antes de enviar la página. El propio navegador elige la primera fuente que sabe mostrar.

## Optimizar un catálogo grande (CRON y CLI)

La herramienta de procesamiento por lotes con AJAX vale para la mayoría de las tiendas. Para miles de imágenes o para automatizar el tratamiento de las nuevas imágenes, usa el cron o la línea de comandos.

### Tarea CRON

Programa una petición regular a la URL que se muestra en el panel _Automatización_ de la configuración. Está protegida por un token:

```
https://tu-tienda/index.php?fc=module&module=datafireflyimageoptimizer&controller=cron&token=TU_TOKEN&scan=1&limit=200
```

El parámetro `scan=1` lanza un análisis antes del procesamiento (útil para detectar nuevas imágenes) y `limit` fija el número de imágenes procesadas por pasada.

### Comando CLI

Para bibliotecas multimedia muy grandes, la línea de comandos procesa la cola en segundo plano, sin timeout:

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

Opciones disponibles: `--scan` (analizar antes de procesar), `--loop` (continuar hasta vaciar la cola), `--limit=N` (tamaño de los lotes), `--types=products,categories` (restringir los destinos para esta ejecución), `--force` (forzar la reconversión aunque los archivos next-gen estén actualizados) y `--quiet` (salida mínima).

## Restauración y reversibilidad

Como los originales nunca se sobrescriben, puedes volver atrás en cualquier momento. En el panel _Mantenimiento_, el botón **Restaurar todo** elimina los archivos `.webp` y `.avif` generados, restaura los originales recomprimidos desde su copia `.dforig`, retira el bloque `.htaccess` y vacía las estadísticas. El mismo panel permite también **regenerar el .htaccess** si es necesario.

Seguridad integrada: si una versión next-gen resulta más pesada que el original (ocurre en algunas imágenes ya muy comprimidas), se descarta automáticamente. El navegador recibe entonces el archivo original.

## Desinstalación

La desinstalación retira el bloque `.htaccess`, elimina las tablas y la configuración del módulo. Los archivos `.webp` y `.avif` ya generados permanecen en el disco. Para partir de una biblioteca multimedia limpia, usa primero **Restaurar todo** en la pestaña Mantenimiento y luego desinstala el módulo.

## Resolución de problemas

**Las imágenes next-gen no se sirven.** En modo Apache, comprueba que `mod_rewrite` y `mod_headers` estén activos y que los archivos `.htaccess` se tengan en cuenta (directiva `AllowOverride`). Confirma también, con las herramientas de tu navegador, que la petición de imagen devuelve efectivamente un tipo `image/avif` o `image/webp`.

- **La prueba de motores falla para AVIF** — tu Imagick/GD probablemente no esté compilado con soporte AVIF. Instala los binarios `avifenc`, o desactiva AVIF y conserva WebP.
- **Página en blanco en el front tras la activación** — suele estar ligado al modo `picture` en un tema muy personalizado. Vuelve al modo `.htaccess` (Apache) o _ninguno_, y luego contacta con el soporte.
- **La conversión es lenta** — reduce el _tamaño de los lotes_, o traslada el procesamiento al cron o a la CLI, diseñados para grandes volúmenes.
- **Algunas imágenes no se convierten** — comprueba que superen el _tamaño mínimo_, que no estén animadas (si la opción está activa) y que ningún patrón de _exclusión_ les afecte.

## Preguntas frecuentes

### ¿Se envían mis imágenes a un servicio externo?

No. Toda la conversión es 100 % local, en tu servidor. Ninguna imagen se transmite a terceros y no hay cuotas ni créditos.

### ¿Se modifican mis archivos originales?

No por defecto: las versiones WebP y AVIF se crean junto al original. Si activas la recompresión de los originales, se conserva una copia `.dforig` para restaurarlos.

### ¿Debo modificar mi tema o mi servidor?

En modo Apache, no: el bloque `.htaccess` se encarga de todo. En Nginx, simplemente activa el modo `picture` en los ajustes.

### ¿Qué formatos se admiten?

El módulo genera WebP y AVIF a partir de tus archivos JPEG, PNG y GIF (no animados).

### ¿Es compatible con PrestaShop 9 y multitienda?

Sí, el módulo es compatible con PrestaShop 1.7.6 a 9.x y funciona en contexto multitienda. Utiliza únicamente hooks oficiales.

### ¿Cómo proceso un catálogo de varios miles de imágenes?

Lanza el análisis y luego la conversión por lotes con AJAX, o programa la tarea CRON o el comando CLI, que procesan la cola en segundo plano sin timeout.