Regenerar miniaturas de WordPress – Guía completa con métodos para todos los niveles (actualizado)

Cambias de tema, abres el sitio y las imágenes destacadas salen borrosas, o subes una galería nueva a un tema que llevas años usando y las miniaturas se ven recortadas de forma rara, con cabezas cortadas y fondos centrados donde no toca.

Pero puede ser aún peor, imagina que añades un tamaño personalizado por código y todas las entradas antiguas lo ignoran como si no existiera.

Bienvenido al clásico dolor de cabeza de las miniaturas en WordPress.

La solución se llama regenerar miniaturas, y aunque suena a operación delicada, es bastante sencilla si entiendes qué está pasando por debajo.

En este tutorial vamos a ver cuándo hace falta regenerar miniaturas, cuándo no hace falta y estás perdiendo el tiempo, y todas las formas de hacerlo, desde el plugin más conocido hasta un comando de WP-CLI o un código personalizado propio para casos concretos.

Cómo funciona el sistema de miniaturas en WordPress

Cuando subes una imagen a la biblioteca de medios WordPress no guarda solo la imagen original sino que genera de forma automática varias copias en distintos tamaños, que son las miniaturas.

Los tamaños por defecto son tres, los que ves en Ajustes > Medios:

• Miniatura (150 × 150 px por defecto, recorte forzado).
• Media (300 × 300 px por defecto, sin recorte forzado).
• Grande (1024 × 1024 px por defecto, sin recorte forzado).

A esos tres se suman los que añade el tema, los que pueden añadir los plugins y algunos que WordPress crea por detrás (como medium_large, que no aparece en los ajustes pero existe).

Al final una sola imagen puede generar entre 6 y 15 archivos en la carpeta /wp-content/uploads/, todos derivados del mismo original.

Cuando publicas una entrada WordPress elige el tamaño adecuado según el contexto (el bucle del tema, el shortcode, el bloque de imagen, etc.) y sirve el archivo que corresponde.

Es así como tu web carga imágenes más pequeñas en móvil y más grandes en escritorio sin que tengas que hacer nada.

El problema aparece cuando se rompe esa correspondencia entre lo que el tema pide y lo que hay generado en el servidor, ahí es donde entra la regeneración.

Cuándo sí hace falta regenerar miniaturas

Hay cuatro escenarios en los que merece la pena regenerar, y fuera de estos casos probablemente estés perdiendo el tiempo.

Has cambiado los tamaños en los ajustes de medios

Si modificas los valores de miniatura, medio o grande, WordPress solo aplica los nuevos tamaños a las imágenes que subas a partir de ese momento. Las que ya tenías se quedan con las dimensiones anteriores así que hay que regenerar para que se adapten.

Has cambiado de tema y los tamaños no coinciden

El nuevo tema registra tamaños diferentes a los que tenía el anterior y las imágenes destacadas salen pixeladas o estiradas porque el tema pide una versión que no existe. WordPress intenta arreglarlo con HTML y CSS, pero el resultado es cutre.

Has añadido un tamaño nuevo con código

Con add_image_size() en functions.php o en un plugin has registrado un tamaño personalizado y ese tamaño solo se genera para las imágenes que subas desde ese momento. Para que las antiguas también lo tengan toca regenerar.

Te han quedado las miniaturas destrozadas por algo raro

Migración, cambio de hosting, problema con las cuotas de disco, plugin de optimización que se volvió loco, plugin de CDN que tocaba donde no debía. A veces aparecen miniaturas corruptas, truncadas o directamente desaparecidas, y la única forma limpia de arreglarlo es regenerar desde el original.

Cuándo NO hace falta regenerar (aunque te lo recomienden)

Mucha gente regenera miniaturas cada vez que actualiza algo «por si acaso» y es un error. Regenerar miles de imágenes consume CPU, memoria y tiempo, y si tu hosting es compartido puedes tirar abajo el servidor durante horas por nada.

No hace falta regenerar si…

• Has cambiado de tema pero el nuevo usa los mismos tamaños (a veces los temas modernos heredan los tamaños estándar y no tocan nada).
• Has instalado un plugin de caché. La caché no genera miniaturas, solo guarda lo ya generado.
• Has instalado un plugin de optimización de imágenes. Estos comprimen lo que ya existe, no crean tamaños nuevos.
• Las imágenes se ven bien. Si no ves ningún problema visual, déjalo estar.

Antes de lanzarte dedica cinco minutos a revisar si realmente tienes un problema. Abre dos o tres entradas viejas, mira las imágenes destacadas, revisa las galerías y comprueba las miniaturas en el feed del tema. Si todo se ve bien guarda la energía del servidor para otra cosa.

Antes de empezar hay cuatro preparativos imprescindibles

Haz una copia de seguridad completa

De la base de datos y de los archivos. Sobre todo de la carpeta /wp-content/uploads/. Si algo sale mal durante la regeneración (corte de luz, timeout del servidor, disco lleno a mitad) puedes quedarte con imágenes a medio generar y sin forma limpia de volver atrás. Con un backup te ahorras el disgusto.

Revisa qué tamaños tienes registrados de verdad

No siempre coincide lo que tú crees con lo que hay. Si tienes WP-CLI instalado con un comando lo ves de un vistazo:

wp media image-size

Te devuelve una tabla con todos los tamaños registrados, su anchura, altura y si están configurados con recorte forzado o proporcional. Muy útil para detectar tamaños huérfanos que ya no usas pero siguen generándose.

Si no tienes WP-CLI, instala el plugin Simple Image Sizes o similar y los verás desde los ajustes de medios.

Calcula cuántas imágenes vas a regenerar

No es lo mismo regenerar 300 imágenes que 30.000. Entra en Medios > Biblioteca y mira el total arriba del listado. Si son muchas lo vas a tener que hacer con WP-CLI o por lotes, un plugin que lo haga por navegador se va a morir a medio camino.

Avisa al hosting si la biblioteca es enorme

En hosting compartido con más de 20.000 o 30.000 imágenes, conviene escribir al soporte antes de lanzar el proceso. No por pedir permiso, sino para que no te suspendan la cuenta pensando que el servidor está bajo ataque cuando ven el pico de consumo.

Opción 1: Regenerate Thumbnails

El clásico de los clásicos. Lo creó Alex Mills (de Automattic) hace más de una década, y sigue disponible en el repositorio oficial mantenido por la comunidad tras su fallecimiento en 2019.

Lo instalas desde Plugins > Añadir nuevo buscando «Regenerate Thumbnails». Una vez activo, lo encuentras en Herramientas > Regenerate Thumbnails.

Tiene tres opciones principales:

• Regenerar miniaturas de todas las imágenes.
• Regenerar miniaturas solo de las imágenes destacadas (suele ser lo único que necesitas si el cambio es por el tema).
• Regenerar una imagen concreta (desde el listado de la biblioteca, con la acción contextual).

Tiene dos casillas importantes:

• Skip regenerating existing correctly sized thumbnails: déjala marcada. Ahorra mucho tiempo porque no vuelve a generar las miniaturas que ya tienen el tamaño correcto.
• Delete old unused sizes: márcala si quieres que borre las miniaturas de tamaños que ya no se usan (por ejemplo, los que dejó un tema anterior). Ojo, porque si alguien enlaza directamente a una de esas URLs desde fuera de tu web, el enlace se romperá.

Es el plugin que suelo recomendar para el 90% de los casos. Sencillo, directo, cumple lo que promete y no toca nada que no debería tocar.

Eso sí, para bibliotecas muy grandes (decenas de miles de imágenes) funciona por peticiones AJAX desde el navegador, así que si cierras la pestaña se para el proceso. Puedes volver a darle a continuar desde donde se quedó, pero es tedioso.

Opción 2: Force Regenerate Thumbnails

Force Regenerate Thumbnails hace lo que dice el nombre, fuerza la regeneración borrando antes todos los tamaños viejos. Es más agresivo que el anterior, pero también más limpio en ciertos escenarios.

Cuándo usar este en vez del clásico:

• Cuando has anulado tamaños antiguos y quieres que desaparezcan del disco.
• Cuando sospechas que hay miniaturas corruptas que no coinciden con el tamaño que debería tener y quieres forzar la regeneración desde cero.
• Cuando la biblioteca tiene archivos huérfanos y ocupa mucho más espacio del que debería.

En las últimas versiones admite WP-CLI con el comando wp force-regenerate-thumbnails y compatibilidad con PHP 8.5. El plugin también tiene una acción por lotes desde el listado de la biblioteca para regenerar solo los adjuntos seleccionados, muy cómoda cuando el problema afecta a un lote concreto y no a toda la web.

Como efecto secundario recupera espacio en disco, a veces varios gigas si tenías la biblioteca llena de basura.

Opción 3: reGenerate Thumbnails Advanced

reGenerate Thumbnails Advanced es una alternativa más moderna con dos ventajas que los anteriores no traen de serie. La primera es una barra de progreso clara con estadísticas al final, la segunda es la función resume, si por lo que sea se para el proceso a medias (se cierra el navegador, timeout del servidor, fallo de red), puedes volver a abrir la página del plugin y retoma por donde iba sin perder el trabajo hecho.

Tiene integración nativa con ShortPixel para optimizar las miniaturas nuevas en el mismo proceso. Si ya usas ShortPixel te ahorras un paso.

La versión gratuita cubre bien la mayoría de casos. La PRO añade WP-CLI, borrado automático de miniaturas huérfanas, limpieza de metadatos y regeneración por intervalos (último día, semana, mes), pensada sobre todo para agencias que gestionan muchos sitios.

Lo recomiendo si tu biblioteca es mediana-grande y te preocupa que un proceso largo se corte a medias.

Opción 4: Plugins de optimización que ya lo traen

Si ya usas un plugin de optimización de imágenes, posiblemente incluya su propia herramienta de regeneración.

Algunos ejemplos:

• Imagify: en el bulk optimizer tiene opción de regenerar al mismo tiempo que comprime.
• ShortPixel: similar, con regeneración integrada en su flujo.
• EWWW Image Optimizer: trae una pestaña específica para ejecutar wp media regenerate desde la interfaz.
• WP Rocket y similares: no regeneran miniaturas, aunque mucha gente lo cree. Solo generan las versiones WebP o AVIF a partir de las miniaturas ya existentes.

Si ya tienes uno de estos instalado revisa si trae la función antes de instalar otro plugin solo para regenerar. Te ahorras un plugin más.

Opción 5: WP-CLI a palo seco

Si tienes acceso SSH al servidor y la biblioteca es grande WP-CLI es con diferencia la mejor opción. Es más rápido porque no tiene el overhead de las peticiones HTTP, no depende del navegador y puedes programarlo, pausarlo y retomarlo con comodidad.

El comando básico regenera todas las miniaturas:

wp media regenerate --yes

El flag --yes evita la confirmación interactiva, que viene bien si lo lanzas desde un cron o un script de despliegue.

Regenerar solo las miniaturas que faltan

Esto es oro puro. Si has añadido un tamaño nuevo con add_image_size() y solo quieres generar ese tamaño para las imágenes antiguas, sin tocar los demás, usa:

wp media regenerate --only-missing --yes

WordPress compara lo que hay con lo que debería haber, y solo genera lo que falta. Rapidísimo comparado con regenerar todo desde cero.

Regenerar un solo tamaño

Si solo quieres regenerar las miniaturas de tamaño grande, por ejemplo:

wp media regenerate --image_size=large --yes

Muy útil cuando cambias únicamente un tamaño en los ajustes de medios y no tiene sentido tocar los demás.

Regenerar imágenes concretas por ID

Si el problema afecta solo a unas pocas imágenes y sabes los IDs:

wp media regenerate 123 124 125

Regenerar un rango de IDs

Para regenerar, por ejemplo, todas las imágenes con ID entre 1.000 y 2.000:

seq 1000 2000 | xargs wp media regenerate

Esto es muy práctico si quieres hacerlo por lotes en servidores que se quedan cortos de memoria.

No borrar las miniaturas viejas

Si tienes enlaces externos a miniaturas concretas (por ejemplo, alguien incrustó una de tus imágenes en su web apuntando a una URL específica), añade el flag para que no las borre:

wp media regenerate --skip-delete --yes

Limpiar solo miniaturas de tamaños no registrados

Otra joya es este comando por si quieres borrar las miniaturas de tamaños que ya no existen en tu configuración (restos de temas y plugins antiguos) sin regenerar nada nuevo:

wp media prune --remove-abandoned --yes

Este prune llegó hace relativamente poco y es una manera limpia de recuperar espacio sin tocar las miniaturas activas.

Tienes la documentación completa del comando en developer.wordpress.org con todas las opciones por si te has quedado con ganas de más.

Opción 6: Código propio para casos concretos

A veces no hace falta instalar un plugin ni tener WP-CLI. Para regenerar una sola imagen desde código (por ejemplo, desde un hook tras subir un archivo por FTP, o desde un script de migración) tienes la función nativa de WordPress:

<?php
/**
 * Regenera las miniaturas de un adjunto concreto.
 *
 * @param int $attachment_id ID del adjunto.
 * @return bool True si se regeneraron, false si algo falló.
 */
function ayudawp_regenerar_miniaturas_adjunto( $attachment_id ) {

    $attachment_id = absint( $attachment_id );

    if ( ! $attachment_id ) {
        return false;
    }

    $file = get_attached_file( $attachment_id );

    if ( ! $file || ! file_exists( $file ) ) {
        return false;
    }

    // Carga las funciones de manipulación de imágenes si no están ya cargadas.
    if ( ! function_exists( 'wp_generate_attachment_metadata' ) ) {
        require_once ABSPATH . 'wp-admin/includes/image.php';
    }

    $metadata = wp_generate_attachment_metadata( $attachment_id, $file );

    if ( is_wp_error( $metadata ) || empty( $metadata ) ) {
        return false;
    }

    wp_update_attachment_metadata( $attachment_id, $metadata );

    return true;
}

Con esto puedes lanzar la regeneración desde cualquier gancho, por ejemplo, al guardar una entrada:

<?php
add_action( 'save_post', 'ayudawp_regenerar_imagen_destacada', 20 );

function ayudawp_regenerar_imagen_destacada( $post_id ) {

    if ( wp_is_post_revision( $post_id ) || wp_is_post_autosave( $post_id ) ) {
        return;
    }

    $thumbnail_id = get_post_thumbnail_id( $post_id );

    if ( $thumbnail_id ) {
        ayudawp_regenerar_miniaturas_adjunto( $thumbnail_id );
    }
}

Este segundo código tienes que usarlo con cuidado, porque si lo dejas activo se va a ejecutar cada vez que guardes cualquier entrada, y eso genera carga innecesaria. Úsalo puntualmente y luego elimínalo.

Para hacerlo a la brava desde un script propio:

<?php
$args = array(
    'post_type'      => 'attachment',
    'post_status'    => 'inherit',
    'post_mime_type' => 'image',
    'posts_per_page' => 100,
    'fields'         => 'ids',
    'no_found_rows'  => true,
);

$imagenes = get_posts( $args );

foreach ( $imagenes as $imagen_id ) {
    ayudawp_regenerar_miniaturas_adjunto( $imagen_id );
}

Este bucle procesa los primeros 100 adjuntos. Para bibliotecas grandes tendrías que paginarlo y probablemente lanzarlo por lotes desde un cron o una tarea en segundo plano para no reventar la memoria.

Regenerar miniaturas en WordPress multisitio

En una instalación de WordPress multisitio la cosa se complica, y por eso casi nadie se atreve a cubrirlo. La mayoría de tutoriales asumen que tienes una instalación estándar y te mandan a ejecutar el plugin o el comando sin más. En una red con 20, 50 o 200 subsitios eso no te sirve.

Vamos por partes.

Cómo se organizan las subidas en multisitio

En una instalación multisitio, las subidas no viven todas juntas en /wp-content/uploads/ como en una web normal. WordPress crea una carpeta separada por cada subsitio en /wp-content/uploads/sites/X/, donde X es el ID del subsitio. El sitio principal de la red sí usa /wp-content/uploads/ directamente, sin subcarpeta.

Esto tiene dos consecuencias prácticas. La primera es que cada subsitio tiene sus propias miniaturas, independientes del resto, y la segunda es que si quieres regenerar todas las miniaturas de toda la red, necesitas recorrer cada subsitio por separado.

Los tamaños registrados pueden variar entre subsitios

Esto sorprende al que viene de una web normal. En multisitio cada subsitio puede tener su propio tema activo, y cada tema registra sus propios tamaños con add_image_size(). Dos subsitios distintos pueden tener conjuntos de tamaños completamente diferentes.

Antes de regenerar en red, lo ideal es revisar qué tamaños tiene cada subsitio. Con WP-CLI lo ves con un bucle rápido:

for SITE_URL in $(wp site list --field=url); do
    echo "=== $SITE_URL ==="
    wp media image-size --url=$SITE_URL
done

Lo lanzas desde la raíz de la instalación y te devuelve la tabla de tamaños registrados para cada subsitio de la red.

Plugins de regeneración en multisitio

Los plugins de regeneración se pueden activar de dos formas en multisitio y la diferencia no es cualquier cosa.

• Activación en red: el superadmin lo activa desde Red > Plugins para todos los subsitios a la vez. Cada administrador de subsitio lo ve en Herramientas y regenera lo suyo.
• Activación por subsitio: cada administrador de subsitio lo activa por su cuenta en su panel.

Regenerate Thumbnails, Force Regenerate Thumbnails y reGenerate Thumbnails Advanced funcionan bien de ambas formas pero con un matiz importante…

Si tu web es una red con subsitios gestionados por personas distintas, activar en red y que cada admin regenere lo suyo es lo más práctico. Si tú como superadmin tienes que mantener todo, activar en red y regenerar cada uno es tedioso y vas a perder la tarde yendo sitio por sitio.

Para redes medianas o grandes WP-CLI es el único camino razonable.

Regenerar con WP-CLI en un subsitio concreto

Por defecto, cuando lanzas wp media regenerate en una instalación multisitio, WP-CLI apunta al sitio principal de la red. Si quieres apuntar a un subsitio concreto, tienes que pasarle el parámetro --url= con la URL del subsitio:

wp media regenerate --url=https://subsitio.midominio.com --yes

O con estructura de subdirectorios:

wp media regenerate --url=https://midominio.com/subsitio --yes

Sin el --url=, el comando solo procesa las imágenes del sitio principal e ignora el resto.

Regenerar toda la red de una sola vez

Aquí es donde multisitio brilla con WP-CLI. Con un bucle de shell recorres todos los subsitios, incluido el principal, y regeneras en cada uno:

for SITE_URL in $(wp site list --field=url); do
    echo "Regenerando $SITE_URL..."
    wp media regenerate --url=$SITE_URL --yes
done

wp site list --field=url te devuelve las URLs de todos los sitios de la red. El bucle las recorre una a una y lanza la regeneración para cada uno.

Si solo quieres regenerar las miniaturas que falten (añadiste un tamaño nuevo con código, por ejemplo), añade el flag --only-missing y reduces drásticamente el tiempo:

for SITE_URL in $(wp site list --field=url); do
    echo "Regenerando $SITE_URL..."
    wp media regenerate --only-missing --url=$SITE_URL --yes
done

Regenerar solo ciertos subsitios de la red

Si tienes una red grande y solo quieres tocar unos subsitios concretos (por ejemplo, los que usan un tema que has actualizado), puedes filtrar por ID o por URL antes de meter el bucle:

for SITE_ID in 3 7 12 15; do
    SITE_URL=$(wp site list --site__in=$SITE_ID --field=url)
    echo "Regenerando $SITE_URL..."
    wp media regenerate --url=$SITE_URL --yes
done

O filtrando por dominio o por parte de la URL:

for SITE_URL in $(wp site list --field=url | grep 'blog-'); do
    echo "Regenerando $SITE_URL..."
    wp media regenerate --url=$SITE_URL --yes
done

Redirigir la salida a un log

Regenerar toda una red de muchos subsitios puede tardar horas. Mejor lanzar el proceso con salida redirigida a un archivo para poder revisarla después:

for SITE_URL in $(wp site list --field=url); do
    echo "=== $SITE_URL ===" >> regen.log
    wp media regenerate --url=$SITE_URL --yes >> regen.log 2>&1
done

Con 2>&1 rediriges también los errores al mismo archivo, y al terminar tienes un log completo con todo lo que ha pasado en cada subsitio.

Lanzarlo en segundo plano con nohup

Si la sesión SSH se te corta (cosa que pasa más de lo que debería en procesos de horas), el comando se interrumpe. Para blindar el proceso, lánzalo con nohup y mándalo al fondo:

nohup bash -c 'for SITE_URL in $(wp site list --field=url); do
    wp media regenerate --url=$SITE_URL --yes
done' > regen.log 2>&1 &

Con esto puedes cerrar la sesión SSH y el proceso sigue corriendo. Para ver el progreso, tail -f regen.log. Para ver si sigue activo, ps aux | grep wp.

Permisos y quién puede regenerar qué

En multisitio, el administrador de un subsitio puede regenerar las miniaturas de su propio subsitio si tiene un plugin activo, pero no puede tocar los demás, eso es lo esperado y deseable.

Solo el superadmin puede regenerar toda la red, y para eso o bien va subsitio por subsitio desde sus escritorios (agotador), o bien tira de WP-CLI (rápido y limpio). Si la red es colaborativa y hay administradores que gestionan sus propios subsitios, conviene dejarles el plugin disponible y que cada uno se ocupe de los suyos cuando haga falta.

Cuotas de subida por subsitio

Muchas redes tienen configurada una cuota máxima de subida por subsitio en Red > Ajustes > Ajustes de carga. Esa cuota se calcula sobre los archivos existentes, incluidas las miniaturas. Si un subsitio está al 95% de su cuota y regeneras con Force Regenerate Thumbnails (que genera primero y borra después), te vas a saltar el límite y el proceso puede fallar.

Para redes con cuotas ajustadas usa WP-CLI con el comportamiento por defecto (que borra antes de crear), o sube temporalmente la cuota antes de regenerar y la bajas después.

Sincronizar tamaños entre subsitios con código

Si en tu red todos los subsitios deben tener los mismos tamaños personalizados, el sitio correcto para registrarlos es un mu-plugin a nivel de red, no el functions.php de un tema. Con un mu-plugin te aseguras de que todos los subsitios reconocen los mismos tamaños, independientemente del tema que tengan activo.

<?php
/**
 * Plugin Name: AyudaWP Tamaños de imagen en red
 * Description: Registra tamaños personalizados comunes a toda la red multisitio.
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

add_action( 'after_setup_theme', 'ayudawp_tamanos_red' );

function ayudawp_tamanos_red() {

    add_image_size( 'ayudawp-tarjeta', 600, 400, true );
    add_image_size( 'ayudawp-destacada-ancha', 1200, 500, true );
    add_image_size( 'ayudawp-cuadrado', 800, 800, true );
}

Este archivo va en /wp-content/mu-plugins/. Los mu-plugins se cargan automáticamente en todos los subsitios de la red y no se pueden desactivar desde el admin de WordPress así que te garantizas que los tamaños están registrados en toda la red siempre.

Regenerar tras añadir tamaños a nivel de red

Cuando registras un tamaño nuevo con un mu-plugin de red, hay que regenerar las miniaturas de todos los subsitios para que ese tamaño exista en las imágenes ya subidas. El mismo bucle de antes con --only-missing hace el trabajo y solo genera el tamaño nuevo, sin tocar los demás:

for SITE_URL in $(wp site list --field=url); do
    wp media regenerate --only-missing --url=$SITE_URL --yes
done

Este es el caso donde --only-missing marca la diferencia. En una red grande, sin ese flag estarías regenerando literalmente todo, gastando horas y recursos para nada.

Multisitio en un hosting que no te deja lanzar procesos largos

Algunos hosting compartidos cortan procesos SSH tras cierto tiempo (típicamente 10 o 15 minutos) y el bucle completo de una red grande tarda mucho más. Si te encuentras en esa situación:

• Divide el trabajo en tandas. Procesa 10 o 20 subsitios por sesión SSH.
• Usa nohup o screen para que el proceso sobreviva a la desconexión.
• Si nada de eso funciona, activa un plugin en red y pide a los administradores de subsitio que ejecuten la regeneración por su cuenta.
• Como último recurso, piensa en si es momento de cambiar a un VPS. Una red multisitio mediana necesita recursos que un compartido no suele ofrecer.

Comprobar el resultado en toda la red

Al terminar de regenerar en red, revisar manualmente subsitio por subsitio es imposible. Para validar que el proceso ha funcionado, un script rápido te dice cuántas imágenes tiene cada subsitio y el tamaño total de su carpeta de uploads:

for SITE_ID in $(wp site list --field=blog_id); do
    SITE_URL=$(wp site list --site__in=$SITE_ID --field=url)
    UPLOAD_DIR="wp-content/uploads/sites/$SITE_ID"

    if [ "$SITE_ID" = "1" ]; then
        UPLOAD_DIR="wp-content/uploads"
    fi

    SIZE=$(du -sh $UPLOAD_DIR 2>/dev/null | cut -f1)
    COUNT=$(find $UPLOAD_DIR -type f 2>/dev/null | wc -l)

    echo "$SITE_URL -> $SIZE / $COUNT archivos"
done

Ten en cuenta que el sitio principal vive en /wp-content/uploads/ directamente, no en sites/1/, por eso el if.

Si ves un subsitio con cero archivos o con un tamaño ridículo comparado con los demás, ahí tienes un candidato a investigar. Y si algún subsitio tiene una cifra desproporcionada de archivos, puede ser señal de que tiene miniaturas huérfanas que merece la pena limpiar con wp media prune --remove-abandoned --yes --url=SUBSITIO.

Problemas frecuentes y cómo resolverlos

La regeneración se queda colgada a mitad

El síntoma típico en bibliotecas grandes cuando usas un plugin por navegador.

Causas habituales:

• Timeout del servidor web (Nginx o Apache cortan a los 30 o 60 segundos).
• Memoria PHP insuficiente (el valor por defecto se queda corto con imágenes grandes).
• El proveedor de hosting limita las peticiones concurrentes.

Las soluciones rápidas pasan por subir los límites en wp-config.php (define( 'WP_MEMORY_LIMIT', '512M' );), alargar el max_execution_time en el php.ini y, si la biblioteca es muy grande, pasarte a WP-CLI. Con WP-CLI no hay timeouts del servidor web porque el comando corre directamente en PHP CLI.

Error fatal por memoria agotada

Con imágenes originales muy grandes (fotos de cámara de 20 o 30 MB), cada regeneración carga la imagen entera en memoria para redimensionarla. Si tienes el límite bajo PHP muere.

Además de subir el WP_MEMORY_LIMIT, asegúrate de que PHP está usando Imagick en vez de GD. Imagick gestiona mejor la memoria con imágenes grandes. Puedes comprobarlo con wp media image-size o instalando un plugin de health check.

WooCommerce y la regeneración en segundo plano

Si cambias los tamaños de las imágenes de producto en WooCommerce intentará regenerar en segundo plano por su cuenta. A veces esto choca con tu propio proceso de regeneración, y acabas con imágenes a medio hacer.

Para desactivarlo temporalmente mientras regeneras tú por WP-CLI o por plugin, añade este filtro:

add_filter( 'woocommerce_background_image_regeneration', '__return_false' );

Déjalo puesto durante tu proceso de regeneración y quítalo después si quieres que WooCommerce vuelva a gestionarlo.

Imágenes que no se regeneran aunque ejecutes el proceso

Suele ser uno de estos tres motivos:

• El archivo original ya no existe en el disco. WordPress no puede regenerar miniaturas si no tiene de dónde sacar la imagen. Revisa que el original esté en /wp-content/uploads/.
• Los permisos de la carpeta uploads no dejan escribir. Normalmente 755 para carpetas y 644 para archivos arregla el tema.
• Un plugin de seguridad o de CDN está sirviendo las imágenes desde otro lado y no ves el cambio aunque se haya hecho. Purga la caché del plugin y del CDN después de regenerar.

Lazy load mostrando la imagen antigua

Regeneras, todo parece correcto, pero sigues viendo las imágenes viejas en el navegador. Caché del navegador. Haz Ctrl+F5 (o Cmd+Shift+R en Mac) para forzar una recarga limpia. Si usas plugin de caché vacíala también.

El original se regenera a partir de un archivo ya reducido

Desde WordPress 5.3, si subes una imagen más grande de 2560 píxeles en cualquiera de sus lados WordPress guarda la original tal cual pero además genera una versión reducida que es la que usa como base para las miniaturas. El archivo original queda como nombre-scaled.jpg y hay un -original por ahí escondido.

Esto se nota cuando regeneras y notas que las miniaturas grandes no se ven tan nítidas como esperabas. Lo que está pasando es que WordPress está regenerando a partir del scaled, no del archivo original de verdad.

Si te molesta, puedes subir ese umbral (o quitarlo del todo) con este filtro en un mu-plugin o en functions.php del tema hijo:

// Subir el umbral a 4000 px.
add_filter( 'big_image_size_threshold', function() {
    return 4000;
} );

// O desactivarlo completamente.
add_filter( 'big_image_size_threshold', '__return_false' );

Ojo, porque desactivarlo en webs con muchas fotos pesadas puede dispararte el uso de CPU al generar miniaturas desde originales enormes.

GD o Imagick ¿cuál es mejor?

WordPress puede usar dos librerías para procesar imágenes, la GD de PHP y ImageMagick (Imagick). Pues salvo opinión contraria, la mía es que Imagick es mejor en casi todo: calidad, rendimiento, soporte de formatos y gestión de memoria con archivos grandes. Pero resulta que muchos hosting vienen solo con GD instalada, y ahí te la juegas con fotos de alta resolución.

Comprueba cuál tiene activa tu WordPress desde Herramientas > Salud del sitio > Información > Gestión de medios. Si pone WP_Image_Editor_GD estás en la versión limitada o tienes que pedir que te activen Imagick.

Si no lo tiene capado tu hosting, puedes probar a forzar Imagick con este filtro:

add_filter( 'wp_image_editors', function( $editors ) {
    return array( 'WP_Image_Editor_Imagick', 'WP_Image_Editor_GD' );
} );

Si tu hosting no tiene Imagick disponible pide que te lo activen. En SiteGround y la mayoría de hosting serios viene activo por defecto o sino puedes activarlo por tu cuenta incluso.

Los SVG no se regeneran y no lo van a hacer

Si tienes SVG en la biblioteca (subidos con Safe SVG o similar), date cuenta de que los SVG son gráficos vectoriales y no tienen tamaños como las imágenes de mapa de bits. No hay miniaturas que regenerar porque el propio SVG escala al tamaño que le pidas sin perder calidad.

Algunos plugins de SVG generan una miniatura PNG para previsualizar en la biblioteca, y esa sí puede llegar a corromperse. En ese caso, la solución pasa por volver a subir el SVG o usar el propio plugin para regenerar el preview.

Las imágenes están en S3, Bunny u otro almacenamiento externo

Si usas WP Offload Media, Bunny Storage, Cloudflare R2 o similar para servir la biblioteca desde un almacenamiento de objetos, regenerar miniaturas tiene un paso extra. Primero se regeneran en local y después el plugin las sube al bucket externo. Durante ese intervalo, las miniaturas de tu web pueden mostrarse rotas.

Recomendaciones para este caso:

• Desactiva temporalmente el offload automático mientras regeneras.
• Regenera en local con WP-CLI.
• Una vez terminado, lanza el proceso de subida masiva que ofrezca tu plugin de offload.
• Purga la caché del CDN al final.

Si lo haces en caliente puedes quedarte con imágenes locales que ya están regeneradas pero el plugin sigue apuntando a las versiones viejas del bucket, y eso genera imágenes desparejadas durante horas.

Cloudflare Polish u otro CDN que toca las imágenes

Cloudflare tiene una función llamada Polish que optimiza imágenes sobre la marcha y las sirve en WebP o AVIF desde sus servidores. Útil, pero si regeneras en origen y no purgas la caché de Cloudflare, vas a seguir viendo las versiones antiguas optimizadas por Polish durante todo el TTL.

El paso obligatorio al terminar de regenerar es purgar la caché del CDN completa, no solo la de HTML. En Cloudflare está en Caching > Configuration > Purge Everything. En Bunny, KeyCDN y otros, busca la opción equivalente.

Elementor, Divi y otros constructores con URLs cacheadas

Los constructores visuales guardan las URLs de las imágenes dentro del HTML compilado de cada plantilla o página. Si regeneras miniaturas y cambian los nombres de archivo (por ejemplo, porque has pasado de 300×200 a 400×300 y el sufijo cambia), Elementor puede seguir pidiendo las URLs viejas.

La solución en Elementor pasa por Herramientas > Regenerar (si no lo han cambiado de sitio). En Divi tienes opciones parecidas en Divi > Opciones del tema > Constructor > Avanzado. Si usas otro constructor, busca la opción de regenerar o limpiar caché del propio plugin.

Cuota de disco agotada o límite de inodes

Regenerar genera archivos nuevos antes de borrar los viejos (salvo que uses Force Regenerate Thumbnails, que borra primero). Si la cuota de disco está al límite, el proceso falla a mitad y te deja la biblioteca a medio camino.

Peor aún en muchos hosting se limita el número de archivos (inodos) además del espacio. Una biblioteca de 10.000 imágenes con 10 tamaños cada una son 100.000 archivos, y si tu plan tiene un límite de 250.000 inodos, cualquier otra cosa que hagas te lo sobrepasa.

Antes de regenerar en masa, comprueba el espacio libre y el uso de inodos en el panel del hosting. Si vas justo usa Force Regenerate Thumbnails para que borre antes de crear, o haz limpieza previa con wp media prune --remove-abandoned --yes.

PHP CLI usa una configuración distinta al PHP web

Este es de los que más dolores de cabeza dan con WP-CLI. Tu PHP para web (el que sirve páginas) y tu PHP CLI (el que ejecuta comandos por SSH) pueden ser versiones distintas, con extensiones distintas y límites distintos.

Un síntoma típico es que por la web todo funciona, pero al lanzar wp media regenerate da error de función no encontrada, o de memoria, o directamente falla sin motivo aparente.

Comprueba qué PHP estás usando en CLI con php -v y php -i | grep memory. Si difiere del web tienes varias opciones:

• En cPanel suele haber un selector específico de PHP CLI separado del de web.
• En SiteGround tienes php83, php84, etc. como comandos distintos, y puedes forzar la versión con php84 $(which wp) media regenerate --yes.

Error «Maximum retries reached» en Regenerate Thumbnails

El plugin clásico tiene un sistema de reintentos cuando una imagen da error. Al tercer fallo seguido te suelta ese mensaje y se para. Suele pasar por una o dos imágenes concretas que están corruptas o que tienen nombres con caracteres raros que el servidor no digiere.

Para identificar cuáles son, mira el log del plugin (en la propia página te indica los IDs problemáticos) y prueba a regenerar solo esos con la acción individual desde la biblioteca de medios. Si siguen fallando, lo más rápido es subir de nuevo el archivo original sustituyendo con Enable Media Replace o reemplazándolo por FTP y corrigiendo el nombre.

Archivos con espacios, tildes o caracteres especiales en el nombre

Un problema menor pero recurrente, sobre todo en bibliotecas viejas. Archivos tipo foto de la reunión.jpg o Campaña 2025 ñ.png pueden dar guerra al regenerar en ciertos servidores (sobre todo con configuraciones antiguas de mod_security o con sistemas de archivos no UTF-8).

Si detectas que el problema se limita a los archivos con caracteres raros, un plugin como Phoenix Media Rename te permite renombrar archivos en masa actualizando todas las referencias en la base de datos, y después de renombrar ya puedes regenerar sin problemas.

Después de regenerar, revisa estas 3 cosas

Antes de dar por terminado el trabajo:

• Abre un par de entradas al azar y comprueba que las imágenes destacadas se ven a la resolución correcta.
• Revisa las galerías y los sliders, que son donde más evidentes se hacen los recortes mal hechos.
• Si tienes WooCommerce, revisa la página de producto y el listado de tienda, porque ahí salen varios tamaños distintos a la vez.

Si usas un CDN o un plugin de caché purga todo después de regenerar. Si no lo haces vas a seguir sirviendo las versiones viejas desde la caché durante horas o días.

Resumen práctico según tu caso

Para que no te pierdas entre tantas opciones aquí va el resumen rápido de qué elegir según tu situación:

• Biblioteca pequeña o mediana (menos de 5.000 imágenes), sin acceso SSH: usa Regenerate Thumbnails, el clásico.
• Biblioteca mediana con miniaturas huérfanas de temas viejos: Force Regenerate Thumbnails para limpiar de paso.
• Proceso largo que te preocupa que se corte: reGenerate Thumbnails Advanced con su función resume.
• Biblioteca grande (más de 10.000 imágenes), con acceso SSH: WP-CLI con wp media regenerate --only-missing.
• Solo has añadido un tamaño nuevo con código y no quieres tocar el resto: WP-CLI con --only-missing o --image_size=nombre_del_tamaño.
• Problema puntual en una o dos imágenes: la acción individual desde la biblioteca de medios, o el snippet PHP si lo haces desde código.

Y si vas a cambiar de tema o de tamaños en una web con muchas visitas hazlo en horario de bajo tráfico y avisa antes al hosting. El proceso consume recursos y es mejor que el servidor esté tranquilo mientras tanto.

Si te surge cualquier duda con la regeneración o te encuentras con un caso raro que no aparece aquí, pásate por los comentarios y lo vemos.

¿Te gustó este artículo? ¡Ni te imaginas lo que te estás perdiendo en YouTube!