Regeneración de imágenes en PrestaShop: Cuándo y cómo reconstruir las miniaturas

Cómo PrestaShop gestiona las imágenes de productos

Cada imagen subida a PrestaShop pasa por un pipeline de procesamiento. Cuando añades una imagen de producto, el sistema almacena el archivo original y luego genera múltiples versiones redimensionadas llamadas miniaturas (thumbnails). Cada miniatura corresponde a un tipo de imagen definido en el back office bajo Diseño > Ajustes de imágenes. Estos tipos de imagen especifican dimensiones exactas en píxeles y están vinculados a contextos específicos: listados de productos, páginas de producto, vistas previas del carrito, cabeceras de categorías, logotipos de fabricantes y más.

PrestaShop almacena las imágenes en el directorio /img/. En PrestaShop 1.7 y 8.x, las imágenes de productos están organizadas usando una estructura de directorios basada en el ID de la imagen. Por ejemplo, una imagen con ID 1234 se almacena en /img/p/1/2/3/4/. Dentro de ese directorio encontrarás la imagen original (nombrada por ID, como 1234.jpg) y todas las miniaturas generadas (como 1234-home_default.jpg, 1234-large_default.jpg, 1234-small_default.jpg).

La convención de nombres sigue el patrón: {image_id}-{image_type_name}.{extension}. Esto significa que cada tipo de imagen que definas crea un archivo adicional por cada imagen de producto en tu catálogo. Una tienda con 5.000 imágenes de producto y 8 tipos de imagen tendrá aproximadamente 45.000 archivos de imagen (5.000 originales más 5.000 por 8 miniaturas). Esta escala importa cuando necesitas regenerarlas.

Comprender los tipos de imagen

Los tipos de imagen están definidos en la tabla de base de datos ps_image_type y se gestionan a través del back office. Cada tipo de imagen tiene un nombre, ancho, alto y flags que indican a qué tipos de entidad se aplica (productos, categorías, fabricantes, proveedores, tiendas). La instalación predeterminada de PrestaShop incluye varios tipos de imagen:

cart_default es típicamente de 125x125 píxeles, usado en el carrito y el mini carrito. small_default es de unos 98x98 píxeles, usado en listados de productos en algunos temas. medium_default es de unos 452x452 píxeles, usado para las miniaturas de productos en la página de producto. home_default es de unos 250x250 píxeles, usado en la página de inicio y listados de categorías. large_default es de unos 800x800 píxeles, usado como la imagen principal del producto en la página de producto.

Los temas pueden definir sus propios requisitos de tipos de imagen. Cuando instalas un nuevo tema, típicamente registra sus tipos de imagen preferidos durante la instalación. El punto crítico es que los archivos de imagen reales en disco deben coincidir con lo que el tema espera. Si el tema requiere home_default a 340x340 pero tus archivos de imagen fueron generados a 250x250 porque usabas un tema diferente anteriormente, cada listado de productos mostrará imágenes con dimensiones incorrectas.

Cuándo es necesaria la regeneración de imágenes

Varias situaciones requieren una regeneración total o parcial de miniaturas. Comprender cuándo es verdaderamente necesaria te ahorra ejecutar un proceso que puede tomar horas en catálogos grandes.

Cambio de tema

Esta es la razón más común. Diferentes temas requieren diferentes dimensiones de imagen. Cuando cambias de un tema a otro, las plantillas del nuevo tema hacen referencia a tipos de imagen con dimensiones específicas. Si esas dimensiones no coinciden con los archivos de miniatura existentes, las imágenes aparecen estiradas, recortadas incorrectamente o borrosas. Después de instalar un nuevo tema, siempre verifica sus requisitos de tipos de imagen y regenera las miniaturas para que coincidan.

Cambios en las dimensiones del tipo de imagen

Si modificas el ancho o alto de un tipo de imagen existente a través de Diseño > Ajustes de imágenes, el cambio solo afecta la definición en la base de datos. Todos los archivos de miniatura existentes en disco conservan sus dimensiones antiguas. Debes regenerar las miniaturas para el tipo de imagen modificado para aplicar las nuevas dimensiones a las imágenes existentes.

Añadir un nuevo tipo de imagen

Cuando creas un nuevo tipo de imagen, aún no existen archivos de miniatura para él. Si una plantilla hace referencia a este nuevo tipo de imagen, mostrará enlaces de imagen rotos hasta que regeneres. El proceso de regeneración crea los archivos de miniatura faltantes para cada imagen existente.

Problemas de calidad de imagen

Si cambias la configuración de calidad de compresión JPEG en PrestaShop (que se encuentra en Rendimiento > Ajustes de imágenes o la sección de configuración de imágenes dependiendo de tu versión), las miniaturas existentes fueron generadas con la configuración de calidad anterior. La regeneración aplica el nuevo nivel de calidad a todas las miniaturas.

Después de una migración o cambio de servidor

A veces durante la migración, los archivos de miniatura se pierden o corrompen mientras las imágenes originales sobreviven. Si las imágenes de productos aparecen rotas pero los originales existen en los directorios esperados, la regeneración recrea todas las miniaturas a partir de los originales.

Habilitar el formato WebP

PrestaShop 8.x introdujo soporte WebP para imágenes de productos. Cuando habilitas la generación WebP, las imágenes existentes no obtienen automáticamente variantes WebP. Debes regenerar las miniaturas para crear las versiones .webp junto a los archivos JPEG o PNG existentes.

Regeneración a través del panel de administración

PrestaShop proporciona una herramienta de regeneración integrada en el back office bajo Diseño > Ajustes de imágenes (o Preferencias > Imágenes en versiones anteriores). En la parte inferior de la página encontrarás la sección de regeneración.

Opciones disponibles

Puedes elegir borrar las imágenes anteriores antes de regenerar. Cuando está habilitado, PrestaShop elimina todas las miniaturas existentes antes de crear nuevas. Esto es útil cuando quieres eliminar miniaturas para tipos de imagen que ya no existen, pero significa que todas las imágenes estarán no disponibles durante el proceso de regeneración. Cuando está deshabilitado, PrestaShop sobrescribe las miniaturas existentes y crea las faltantes sin eliminar nada primero.

Puedes seleccionar qué tipos de entidad regenerar: productos, categorías, fabricantes, proveedores o tiendas. Si solo cambiaste las dimensiones de imágenes de productos, no hay necesidad de regenerar imágenes de categorías o fabricantes.

Limitaciones del enfoque del panel de administración

La regeneración del panel de administración se ejecuta como una solicitud web. Esto crea varios problemas para catálogos grandes. Los servidores web tienen límites de tiempo de ejecución, típicamente de 30 a 300 segundos dependiendo de tu configuración. Una tienda con 10.000 imágenes de producto y 8 tipos de imagen necesita generar 80.000 archivos de miniatura. Incluso a un ritmo generoso de 10 imágenes por segundo, eso toma más de dos horas. La mayoría de los servidores web terminarán el proceso mucho antes de que finalice.

Los límites de memoria también aplican. Cada imagen debe cargarse en memoria, redimensionarse usando GD o ImageMagick, y guardarse. Las imágenes originales de alta resolución pueden consumir de 20 a 50 MB de memoria cada una durante el procesamiento. El límite de memoria predeterminado de PHP de 128 MB o 256 MB puede agotarse rápidamente, especialmente al procesar imágenes en secuencia sin una limpieza de memoria adecuada.

Si el proceso es interrumpido por un timeout o error de memoria, terminas con un catálogo parcialmente regenerado. Algunos productos tienen nuevas miniaturas, otros tienen las antiguas y algunos podrían no tener ninguna. Este estado inconsistente es peor que el problema original.

Regeneración CLI para catálogos grandes

Para tiendas con más de unos pocos cientos de productos, la regeneración por línea de comandos es fuertemente recomendada. Evita los límites de timeout del servidor web y puede configurarse con límites de memoria más altos.

Uso de la consola PrestaShop

PrestaShop 1.7.5 y posteriores incluyen una consola Symfony. Puedes regenerar miniaturas usando:

php bin/console prestashop:image:regenerate

Este comando acepta varias opciones. Para regenerar solo tipos de imagen específicos, usa el flag --image-type seguido del nombre del tipo de imagen. Para procesar solo productos, categorías u otros tipos de entidad específicos, usa el flag --entity. El flag --format te permite especificar qué formatos de salida generar (jpg, png, webp).

Ejecuta el comando desde el directorio raíz de PrestaShop. Si usas Docker, ejecútalo dentro del contenedor:

docker exec -u www-data your-container php bin/console prestashop:image:regenerate

El flag -u www-data asegura que los archivos generados sean propiedad del usuario del servidor web. Ejecutar como root crea archivos que el servidor web no puede servir ni modificar posteriormente.

Configuración de memoria y tiempo

Para la ejecución CLI, puedes aumentar los límites de PHP directamente en el comando:

php -d memory_limit=512M -d max_execution_time=0 bin/console prestashop:image:regenerate

Establecer max_execution_time=0 elimina completamente el límite de tiempo, y 512 MB de memoria son suficientes para la mayoría de los catálogos. Para tiendas con originales de resolución extremadamente alta (4000x4000 píxeles o más), podrías necesitar 1 GB o más.

Enfoque de regeneración personalizado

Para catálogos muy grandes (50.000 o más imágenes), incluso el comando de consola puede ser lento o problemático. Un enfoque PHP personalizado te permite procesar imágenes en lotes con seguimiento de progreso, manejo de errores y la capacidad de reanudar después de una interrupción.

El enfoque consiste en consultar la base de datos para todos los registros de imagen, iterar a través de ellos en lotes de 100 o 200, generar miniaturas para cada imagen y registrar el progreso. Si el proceso se interrumpe, puedes reanudarlo desde donde se detuvo verificando qué miniaturas ya existen.

Un enfoque por lotes también permite distribuir la regeneración en múltiples ejecuciones durante las horas de menor tráfico, evitando el impacto en el rendimiento de la tienda activa.

Generación WebP durante la regeneración

WebP es un formato de imagen moderno que proporciona tamaños de archivo significativamente menores que JPEG a calidad comparable. PrestaShop 8.x puede generar versiones WebP de las miniaturas durante el proceso de regeneración.

Habilitar el soporte WebP

Antes de regenerar, habilita WebP en la configuración de PrestaShop. En PrestaShop 8.x, esta opción está en los ajustes de imágenes. Cuando está habilitada, el proceso de regeneración crea tanto la miniatura tradicional JPEG/PNG como una versión .webp para cada tipo de imagen.

Requisitos del servidor

La generación WebP requiere la extensión GD compilada con soporte WebP (--with-webp) o la extensión ImageMagick con delegados WebP. Puedes verificar el soporte GD con phpinfo() o gd_info(). Busca WebP Support en la salida. Si el soporte WebP falta, el proceso de regeneración silenciosamente omite la creación WebP sin producir errores.

Consideraciones de espacio en disco

Los archivos WebP son típicamente del 25 al 35 por ciento más pequeños que los archivos JPEG equivalentes, pero estás almacenando ambos formatos. Una tienda con 40.000 miniaturas JPEG que ocupan 2 GB de espacio en disco necesitará aproximadamente 3,4 GB en total después de la generación WebP (los 2 GB originales más aproximadamente 1,4 GB de archivos WebP). Planifica tu espacio en disco en consecuencia antes de iniciar una regeneración completa.

Servir WebP a los navegadores

Generar archivos WebP es solo la mitad de la solución. Tu tema y servidor deben estar configurados para servir WebP a los navegadores que lo soportan con fallback a JPEG/PNG para los que no. Esto se maneja típicamente a través de elementos <picture> en las plantillas del tema o mediante negociación de contenido del lado del servidor usando el encabezado Accept.

En Apache, puedes añadir reglas de reescritura que verifican el soporte WebP y sirven la versión WebP cuando está disponible. En Nginx, la directiva try_files puede verificar si existe una versión .webp de la imagen solicitada y servirla si el encabezado Accept del navegador incluye image/webp.

Impacto en el rendimiento y mitigación

La regeneración de imágenes es intensiva en CPU y pesada en E/S. En una tienda activa, puede degradar significativamente el rendimiento si no se gestiona cuidadosamente.

Impacto en la CPU

Cada operación de redimensionamiento de imagen requiere cargar el original en memoria, ejecutar el algoritmo de redimensionamiento, aplicar las configuraciones de calidad/compresión y escribir el resultado en disco. La operación de redimensionamiento en sí es computacionalmente costosa, especialmente para imágenes grandes que se reducen a miniaturas pequeñas. En un entorno de hosting compartido, esto puede saturar la CPU y ralentizar toda la tienda.

Impacto en E/S

La regeneración lee cada imagen original y escribe múltiples archivos de miniatura. En discos duros tradicionales, esto crea una carga de E/S significativa. En almacenamiento SSD, el impacto es mucho menor pero aún notable a escala. El patrón de E/S es particularmente hostil para los discos giratorios porque involucra lecturas aleatorias (originales dispersos por directorios) combinadas con escrituras secuenciales (miniaturas en los mismos directorios).

Ejecutar la regeneración en horas de bajo tráfico

Programa la regeneración para tu período de menor tráfico. Para tiendas europeas, esto es típicamente entre las 2:00 y las 6:00 de la madrugada. Para tiendas con tráfico global, puede que no haya un verdadero periodo de bajo tráfico, pero puedes identificar puntos relativamente bajos a partir de tus datos de analytics.

Uso de nice e ionice

En servidores Linux, puedes reducir la prioridad del proceso de regeneración para que no prive a otros procesos de recursos. El comando nice reduce la prioridad de CPU, e ionice reduce la prioridad de E/S:

nice -n 19 ionice -c 3 php bin/console prestashop:image:regenerate

Un valor nice de 19 es la prioridad más baja. La clase ionice 3 es la clase idle, lo que significa que el proceso solo obtiene tiempo de E/S cuando nada más lo necesita. Esto reduce drásticamente el impacto en la tienda activa pero hace que la regeneración tarde más.

Escalado temporal

Si estás en un servidor en la nube, considera escalar temporalmente tu servidor (más cores de CPU, más RAM, almacenamiento más rápido) durante la duración de la regeneración, y luego reducir. El costo extra de unas pocas horas de recursos de nivel superior es usualmente mínimo comparado con el impacto de una regeneración lenta de varios días en el rendimiento de tu tienda.

Evitar timeouts durante la regeneración

Los timeouts son el problema más común con la regeneración de imágenes. Aquí están las configuraciones específicas que los previenen.

Configuración PHP

La directiva max_execution_time limita cuánto tiempo puede ejecutarse un proceso PHP. Para la ejecución CLI, típicamente ya está establecida en 0 (ilimitado), pero verifica comprobando php -i | grep max_execution_time. Para la regeneración web a través del panel de administración, aumenta este valor en tu php.ini o .htaccess:

php_value max_execution_time 7200

También aumenta max_input_time si usas el panel de administración, ya que el timeout de envío del formulario es separado del timeout de ejecución:

php_value max_input_time 7200

Timeout del servidor web

La directiva Timeout de Apache y proxy_read_timeout / fastcgi_read_timeout de Nginx pueden terminar solicitudes de larga duración incluso si PHP mismo no ha superado el timeout. Para Apache: Timeout 7200. Para Nginx, añade a tu bloque server: fastcgi_read_timeout 7200; o proxy_read_timeout 7200;.

Configuración PHP-FPM

Si usas PHP-FPM (como la mayoría de las configuraciones modernas), el request_terminate_timeout en la configuración de tu pool también puede matar procesos de larga duración. Establécelo en 0 para deshabilitar el timeout, o iguálalo al tiempo máximo de ejecución deseado:

request_terminate_timeout = 7200

Timeouts de Cloudflare y CDN

Si tu tienda está detrás de Cloudflare u otro CDN, el CDN tiene su propio timeout de solicitudes (el plan gratuito de Cloudflare tiene un timeout de 100 segundos). Esto hace que la regeneración por panel de administración detrás de un CDN sea efectivamente imposible. Debes usar la regeneración CLI, evitar el CDN para el acceso de administración, o usar una solución que procese imágenes de forma asíncrona.

Estrategias de regeneración incremental

La regeneración completa procesa cada imagen en el catálogo. Para tiendas con decenas de miles de imágenes, esto puede tomar muchas horas. Los enfoques incrementales procesan solo las imágenes que realmente necesitan nuevas miniaturas.

Regeneración selectiva de tipo de imagen

Si solo añadiste o modificaste un tipo de imagen, no necesitas regenerar todos los tipos de imagen. Usa la opción --image-type en el comando de consola para apuntar solo al tipo de imagen específico que cambió. Esto reduce el trabajo a un octavo (o cualquier fracción de tus tipos de imagen totales) de una regeneración completa.

Procesamiento basado en fecha

Si necesitas regenerar miniaturas solo para productos añadidos recientemente (por ejemplo, después de corregir un problema de procesamiento de imágenes), puedes consultar la base de datos para imágenes añadidas después de una fecha específica y procesar solo esas. La tabla ps_image no tiene una columna de fecha por defecto, pero la tabla asociada ps_product tiene campos date_add y date_upd que pueden usarse para identificar productos modificados recientemente.

Detección de miniaturas faltantes

En lugar de regenerar todo, escanea los directorios de imágenes para encontrar imágenes a las que les faltan miniaturas específicas y regenera solo esas. Este es el enfoque más rápido cuando has añadido un nuevo tipo de imagen o cuando una regeneración parcial fue interrumpida.

La lógica es directa: para cada ID de imagen en la base de datos, verifica si el archivo de miniatura esperado existe en disco. Si no existe, regenera solo esa miniatura. Esto convierte una regeneración completa de varias horas en un proceso dirigido que podría tomar minutos.

Procesamiento paralelo

Para catálogos muy grandes, puedes dividir el rango de IDs de imagen en bloques y procesarlos en paralelo usando múltiples procesos PHP. Por ejemplo, un proceso maneja los IDs de imagen de 1 a 10000, otro maneja de 10001 a 20000, y así sucesivamente. Cada proceso funciona independientemente, y el throughput combinado es aproximadamente proporcional al número de procesos paralelos (limitado por los cores de CPU y el ancho de banda de E/S).

Ten cuidado con el procesamiento paralelo y la E/S de disco. Ejecutar demasiados procesos simultáneamente en un disco duro tradicional causará contención de E/S y realmente ralentizará las cosas. En almacenamiento SSD, de 4 a 8 procesos paralelos típicamente funcionan bien.

Consideraciones sobre el formato de imagen

PrestaShop soporta JPEG, PNG y GIF como formatos fuente, y puede generar miniaturas en estos formatos más WebP. El formato fuente afecta el comportamiento de la regeneración.

Imágenes JPEG

JPEG es el formato más común para fotos de productos. Soporta compresión con pérdida, lo que significa que cada vez que se guarda un JPEG, se pierde algo de calidad. Por eso regenerar miniaturas desde las subidas originales produce mejores resultados que regenerar desde miniaturas previamente redimensionadas. Siempre asegúrate de estar trabajando desde la imagen original subida, no desde una miniatura generada previamente.

Imágenes PNG

PNG soporta transparencia y compresión sin pérdida. Si tus imágenes de producto usan fondos transparentes, las miniaturas PNG preservan esa transparencia. Sin embargo, los archivos PNG son típicamente mucho más grandes que los archivos JPEG. Considera si realmente necesitas la transparencia. Si no, convertir las imágenes de producto PNG a JPEG durante la regeneración puede reducir significativamente el espacio en disco y mejorar los tiempos de carga de página.

Manejo de GIF

PrestaShop puede aceptar subidas GIF, pero las miniaturas generadas desde fuentes GIF son estáticas (la animación no se preserva). Si tienes imágenes de producto GIF animadas, ten en cuenta que la regeneración produce miniaturas estáticas del primer fotograma.

Verificación post-regeneración

Después de que la regeneración se complete, verifica los resultados antes de asumir que todo está correcto.

Verificación visual de la calidad de imágenes

Abre varias páginas de producto e inspecciona las imágenes visualmente. Verifica que las miniaturas sean nítidas, correctamente proporcionadas y no estén estiradas ni pixeladas. Presta especial atención a las imágenes que eran originalmente pequeñas (cercanas o menores que las dimensiones de la miniatura), ya que estas tienen más probabilidades de mostrar problemas de calidad al ser ampliadas.

Verificación del conteo de archivos

Compara el número de miniaturas generadas con las expectativas. Si tienes 5.000 imágenes de producto y 8 tipos de imagen, deberías tener aproximadamente 40.000 archivos de miniatura (más los originales y potencialmente las variantes WebP). Un conteo significativamente menor indica que el proceso de regeneración fue interrumpido o encontró errores en algunas imágenes.

Verificación de permisos de archivos

Verifica que los archivos regenerados sean propiedad del usuario del servidor web (típicamente www-data en Debian/Ubuntu o apache en CentOS). Si ejecutaste la regeneración como root, los archivos podrían no ser legibles por el servidor web, causando imágenes rotas en el frontend. Corrige con: chown -R www-data:www-data img/p/.

Limpieza de caché

Después de la regeneración, limpia todas las cachés. Esto incluye la caché interna de PrestaShop (Parámetros avanzados > Rendimiento), cualquier caché de opcode (OPcache) y cualquier caché CDN o proxy inverso. Las páginas cacheadas antiguas podrían seguir haciendo referencia a URLs o dimensiones de imagen antiguas. Si usas un módulo que genera sprites CSS o imágenes inline, regenéralos también.

Si tu tienda está detrás de Cloudflare, purga la caché para la ruta /img/ o haz una purga completa de caché. Cloudflare cachea imágenes agresivamente, y los visitantes podrían ver miniaturas antiguas hasta que la caché del CDN expire o sea purgada.

Resolución de problemas comunes de regeneración

Miniaturas negras o corrompidas

Esto generalmente indica un problema con la librería GD. La extensión GD podría no soportar el formato fuente (por ejemplo, GD compilado sin soporte JPEG). Verifica las capacidades de GD con gd_info(). Otra causa es memoria insuficiente: si PHP no puede asignar suficiente memoria para cargar la imagen original, GD podría producir una imagen negra en lugar de lanzar un error.

Dimensiones incorrectas en las miniaturas generadas

Si las miniaturas tienen dimensiones inesperadas, verifica las definiciones de tipos de imagen en la base de datos. El panel de administración podría mostrar un valor mientras la base de datos contiene otro (esto puede suceder después de una importación fallida o una modificación manual de la base de datos). Consulta directamente: SELECT * FROM ps_image_type WHERE name = 'home_default';

La regeneración se cuelga sin progreso

Un proceso de regeneración colgado generalmente significa que encontró una imagen muy grande que agotó la memoria disponible. Verifica el log de errores PHP buscando fallos de asignación de memoria. La solución es aumentar el límite de memoria o pre-procesar las imágenes fuente problemáticas para reducir su resolución antes de la regeneración.

Errores de permiso denegado

Si la regeneración reporta errores de permiso, el proceso PHP no puede escribir en los directorios de imágenes. Esto ocurre comúnmente en entornos Docker donde los volúmenes bind-mounted tienen diferente propiedad dentro y fuera del contenedor. Asegúrate de que el usuario que ejecuta el comando de regeneración tenga acceso de escritura al árbol completo del directorio /img/.

Resumen

La regeneración de imágenes es una tarea de mantenimiento que todo propietario de tienda PrestaShop encuentra, generalmente durante un cambio de tema o al optimizar los ajustes de imagen. Para catálogos pequeños (menos de 500 productos), la herramienta del panel de administración funciona adecuadamente. Para cualquier cosa mayor, la regeneración CLI es el único enfoque fiable. Los principios clave son: siempre trabaja desde las imágenes originales, haz coincidir las definiciones de tus tipos de imagen con los requisitos de tu tema, gestiona proactivamente los recursos del servidor y los timeouts, usa enfoques incrementales cuando sea posible y verifica los resultados después de que el proceso se complete. Con WebP convirtiéndose en el estándar para imágenes web, la regeneración también sirve como el mecanismo para crear variantes de formato moderno de todo tu catálogo de productos, ofreciendo tamaños de archivo más pequeños y cargas de página más rápidas a tus clientes.