Por qué las imágenes de WordPress se ven borrosas al subirlas (y cómo solucionarlo)

Nueve de cada diez veces tus imágenes no están realmente borrosas: WordPress las redujo al subirlas y ahora sirve la copia recortada. Desde WordPress 5.3, cualquier imagen con un ancho o alto mayor de 2560px es reemplazada de forma silenciosa por una versión -scaled limitada a 2560px en su lado más largo, y ese archivo más pequeño es el que tu tema estira para rellenar una cabecera, un bloque a todo el ancho o una pantalla retina. La solución consiste en demostrar que eso es lo que pasó y, a partir de ahí, subir el umbral o dejar de subir imágenes que necesiten ser más grandes que la caja donde van a ir.

Por qué ocurre

Cuando subes una foto, WordPress ejecuta wp_create_image_subsizes() (en wp-admin/includes/image.php). Si el lado más largo supera el big_image_size_threshold —2560px por defecto—, llama a _wp_image_meta_replace_original(), genera your-photo-scaled.jpg y reescribe los metadatos del adjunto para que el tamaño full apunte ahora a la copia escalada. Tu original real se conserva en disco como your-photo.jpg y queda referenciado por wp_get_original_image_path(), pero nada en el frontend lo sirve. Todos los tamaños intermedios y todos los candidatos de srcset se generan a partir del archivo escalado de 2560px, no de lo que subiste.

Así que aquí está la causa del desenfoque. Subes una imagen nítida de 4000px para una cabecera a sangre completa. WordPress la limita a 2560px. En una pantalla estándar dentro de un contenedor de 1600px de ancho, no hay problema. En una pantalla retina 2x, el navegador necesita aproximadamente 3200 píxeles reales para rellenar ese contenedor con nitidez, solo tiene 2560 y escala hacia arriba la diferencia. Bordes suaves, texto dentro de la imagen emborronado: exactamente el síntoma de “borrosa al subirla”.

La otra mitad del mismo problema es que srcset elige un tamaño demasiado pequeño. Si tu tema declara un ancho de contenido que no coincide con la caja realmente renderizada, WordPress le entrega al navegador un intermedio -1024x683 o -1536x1024 y este se estira hacia arriba. Misma causa —caja de visualización más grande que los píxeles disponibles—, distinto detonante.

Comprueba qué sirvió WordPress realmente

No lo adivines. Haz clic derecho sobre la imagen borrosa, ábrela en una pestaña nueva y mira el nombre del archivo en la URL. Si termina en -scaled.jpg o con un sufijo de dimensiones como -1024x683.jpg, lo has confirmado: el navegador está renderizando un derivado reducido, no tu subida. También puedes inspeccionar el elemento y leer currentSrc para ver exactamente qué candidato eligió el navegador.

Para ver el panorama completo antes de volver a subir nada, arrastra la imagen a la herramienta de tamaños de imagen de WordPress: te muestra todos los derivados que WordPress generará a partir de ese archivo exacto, incluyendo si se crea una copia -scaled y con qué dimensiones, para que sepas de antemano si tu origen es lo bastante grande para el lugar donde lo vas a colocar.

En el servidor puedes listar todos los archivos recortados:

find wp-content/uploads -name '*-scaled.*'

Cómo solucionarlo, por orden

1. Si tus imágenes de verdad necesitan ser más grandes de 2560px (cabeceras grandes, retina, galerías con calidad de impresión), sube el umbral:

// functions.php or a small mu-plugin
add_filter( 'big_image_size_threshold', function () {
    return 3840; // longest edge, in pixels
} );

O desactiva el límite por completo:

add_filter( 'big_image_size_threshold', '__return_false' );

2. Vuelve a subir las imágenes afectadas. Este es el paso que la gente se salta. Cambiar el umbral solo afecta a las subidas nuevas. Las imágenes que ya están en tu biblioteca conservan sus metadatos antiguos, y regenerar las miniaturas reconstruye los tamaños intermedios a partir del archivo -scaled recortado: no recupera la resolución que se descartó. El camino fiable es: cambiar el filtro, borrar el adjunto y volver a subirlo.

3. Si tu origen ya es ≤2560px y aun así se ve borroso, el umbral no es tu problema: la caja de visualización es más grande que la imagen. Sube un origen más grande o reduce el contenedor. Para nitidez retina, tu origen debe tener aproximadamente el doble del ancho en píxeles CSS de la caja que rellena.

4. Solo después de lo anterior, regenera las miniaturas para que los tamaños intermedios sean coherentes, pero ten claro que es limpieza, no una cura.

Qué no hacer

No subas la calidad JPEG a 100. WordPress comprime con una calidad por defecto de 82 mediante wp_editor_set_quality, y la mitad de los consejos que hay en internet te dicen que la sobrescribas:

add_filter( 'wp_editor_set_quality', function () { return 90; } );

Está bien para reducir los artefactos de compresión, pero una imagen estirada y escalada hacia arriba es un problema de resolución, no de compresión. Pasar de 82 a 100 infla tus archivos y casi no hace nada por el desenfoque que estás viendo.

No desactives -scaled por reflejo. Apagar el límite (hay una herramienta para eso) es lo correcto si sirves imágenes por encima de 2560px, pero si tu problema real es un intermedio demasiado pequeño que se estira, desactivarlo no cambia nada y pierdes el ahorro de ancho de banda sin motivo. Diagnostica primero.

No culpes a la caché ni regeneres las miniaturas primero. La regeneración lee del mismo origen recortado, así que no puede restaurar el detalle. Vaciar un CDN o la caché de página no tocará un archivo que ya era pequeño en disco de entrada.

No recurras al CSS del tema ni a object-fit. Ninguna cantidad de estilos añade píxeles. Si el archivo servido termina en -scaled o con un sufijo de dimensiones, el problema es el archivo, no la maquetación.

¿Sigues atascado?

Si has confirmado que el archivo servido es tu subida a resolución completa —sin -scaled, sin sufijo de dimensiones— y aun así se ve suave, comprueba si algún plugin (un optimizador, un redimensionador de imágenes por CDN o una librería de carga diferida) está reescribiendo tu src hacia un proxy comprimido. Pasa la imagen por la herramienta de tamaños de imagen para confirmar qué debería estar generando WordPress y luego compáralo con lo que el navegador carga realmente. Cuando esos dos no coinciden, algo entre WordPress y el navegador es el culpable.