Componente Image de Next.js: sizes, preload e imágenes remotas
Guía del componente Image de Next.js
Next.js Image: sizes, preload, remotePatterns y LCP | We.Inc
Cómo funciona next/image en Next.js 16: width, height y fill, una calculadora de sizes, preload en lugar de priority, remotePatterns, qualities y los anchos srcset por defecto.
Importa Image desde next/image y dale src, alt y, o bien width y height, o bien fill. Añade una cadena sizes siempre que el ancho renderizado cambie con la pantalla, para que el navegador descargue un archivo más pequeño. Para la imagen principal que es tu LCP, usa preload (sustituyó a priority en Next.js 16). Permite hosts externos con images.remotePatterns.
Las props que deciden la velocidad
Prop
Valor por defecto
Úsala cuando
width / height
La imagen tiene un tamaño fijo o quieres reservar la relación de aspecto
El contenedor padre decide el tamaño (tarjetas, cabeceras, portadas)
el navegador asume 100vw
La imagen es adaptable o usa fill
La imagen es el elemento LCP visible sin desplazarse
Usa eager solo en imágenes que deben cargarse de inmediato
Solo se sirven los valores incluidos en images.qualities
En Next.js es fácil cometer dos errores con las imágenes: una imagen fill sin sizes, de modo que los teléfonos descargan archivos de escritorio, y una imagen principal que espera a la carga diferida. Esta página explica cada prop con palabras sencillas, te da una calculadora que escribe la cadena sizes para tu diseño y enumera los valores de configuración por defecto que usa Next.js hoy.
Elige el diseño en el que va tu imagen, como ancho completo, dos columnas o una cuadrícula de tres tarjetas.
Indica los puntos de corte que usa tu CSS. La calculadora escribe el valor sizes correspondiente.
Elige un ancho de teléfono y una densidad de píxeles para ver qué ancho srcset por defecto descargaría probablemente el navegador.
Copia el elemento Image terminado y pégalo en tu componente.
Las importaciones estáticas (import hero from './hero.jpg') rellenan por ti width, height y blurDataURL, así que úsalas para las imágenes que viven en el repositorio.
Da a una imagen fill un padre con position: relative y una altura real; si no, se queda sin tamaño.
Solo una imagen por viewport debería llevar preload. Marcar varias anula la ventaja y las hace competir por el ancho de banda.
Mantén remotePatterns acotado: indica el protocolo, el hostname exacto y un prefijo de ruta en lugar de permitir un dominio entero.
Si pasas un valor de calidad que no está en images.qualities, Next.js sirve el valor permitido más cercano y avisa en desarrollo.
Preguntas frecuentes
¿La prop priority está obsoleta?
Sí. Desde Next.js 16 la documentación marca priority como obsoleta en favor de preload, que inserta un enlace de precarga en el head. La documentación también dice que en la mayoría de los casos loading="eager" o fetchPriority="high" es mejor opción, y que preload no debe combinarse con ninguna de esas props.
¿Por qué next/image dice que el hostname no está configurado?
Las imágenes externas deben coincidir con una entrada de images.remotePatterns en next.config. Añade un objeto con protocol, hostname y un pathname como /photos/** y reinicia el servidor de desarrollo. Las solicitudes que no coinciden con ningún patrón reciben una respuesta 400 del optimizador de imágenes.
¿Qué cambia realmente la prop sizes?
Le dice al navegador qué ancho tendrá la imagen en cada punto de corte antes de que cargue el CSS. Con sizes, Next.js también genera un srcset completo basado en anchos (640w, 750w, etc.) en lugar de solo 1x y 2x, así que un teléfono puede elegir un archivo mucho más pequeño.
¿Necesito width y height con fill?
No. fill y width/height son alternativas. Con fill la imagen se estira hasta su padre posicionado, y controlas el recorte con object-fit mediante la prop style o className.
¿Cuánto tiempo se guardan en caché las imágenes optimizadas?
El valor por defecto de minimumCacheTTL es 14400 segundos, es decir, cuatro horas. La duración real es el mayor de dos valores: ese o la cabecera Cache-Control que envía la imagen original. Las imágenes importadas de forma estática reciben una caché inmutable de larga duración porque sus nombres de archivo llevan hash.
Por qué existe el componente
Una etiqueta img normal envía el mismo archivo a todos los dispositivos. next/image redimensiona el original bajo demanda, lo convierte a un formato moderno que acepte el navegador, lo carga en diferido por defecto y reserva el espacio para que el diseño no salte mientras llega.
El problema es que solo puede elegir un archivo sensato si sabe qué ancho tendrá la imagen. Ese es el trabajo de width, height y sizes, y es donde ocurren la mayoría de los errores reales.
Cómo acertar con el LCP
El Largest Contentful Paint suele ser una foto principal. Cargar esa foto en diferido retrasa la métrica, así que márcala con preload, o con loading="eager" más fetchPriority="high", y deja todas las imágenes de más abajo con la carga diferida por defecto.
Combínalo con un valor sizes honesto. Una imagen principal que ocupa todo el ancho en teléfonos pero solo media página en escritorio debe indicarlo; si no, tanto las pantallas grandes como las pequeñas reciben el archivo equivocado.
La configuración que vas a tocar
remotePatterns enumera los hosts externos en los que confías. qualities es una lista de valores de calidad permitidos, obligatoria desde Next.js 16, y la documentación la deja en 75 por defecto. formats te permite añadir AVIF por delante de WebP, a costa de guardar ambas versiones en la caché.
deviceSizes e imageSizes forman juntos los anchos candidatos de cada srcset. Rara vez necesitas cambiarlos, pero conocer los valores por defecto te ayuda a interpretar lo que descargó el navegador en el panel de red.
Todas las props que probablemente usarás
Props de next/image (referencia de Next.js 16)
Prop
Tipo
Qué hace
string o importación estática
Ruta local en public, archivo importado o URL externa permitida por remotePatterns
Texto alternativo obligatorio; usa una cadena vacía solo para imágenes decorativas
width, height
entero (px)
Tamaño intrínseco usado para la relación de aspecto; no hace falta con importaciones estáticas ni con fill
Se estira hasta el padre posicionado en lugar de usar width y height
Condiciones de medios y anchos de hueco que guían la selección del srcset
entero de 1 a 100
Calidad de salida, 75 por defecto, ajustada a la lista images.qualities
Añade un enlace de precarga en el head para la imagen LCP
lazy o eager
Por defecto es lazy
empty, blur o data URL
Lo que se muestra mientras carga; blur necesita blurDataURL salvo que la imagen sea una importación estática
Sirve el archivo original tal cual, sin redimensionar ni cambiar el formato
Obsoleta en Next.js 16; usa preload en su lugar
Valores por defecto de la configuración de imágenes
Ajustes de images en next.config y sus valores por defecto
Ajuste
Valor por defecto
Notas
deviceSizes
Anchos para imágenes de ancho completo y fill
imageSizes
Anchos extra pequeños, solo se usan cuando la imagen tiene la prop sizes
Lista de permitidos obligatoria desde Next.js 16
minimumCacheTTL
14400 (4 horas)
Gana el mayor entre este valor y el Cache-Control del origen
remotePatterns
Cada host externo debe aparecer en la lista
Ejemplos para copiar
Imagen principal desde una importación estática
La importación da a Next.js las dimensiones reales y un marcador difuminado. preload inicia la descarga desde el head.
Cuadrícula de tarjetas con fill y sizes
Cada tarjeta ocupa un tercio de la página en escritorio, la mitad en tabletas y todo el ancho en teléfonos, y el valor sizes dice exactamente eso.
next.config.ts para un host de imágenes remoto
Solo se permiten archivos HTTPS bajo /uploads/ en un único host. Se admiten dos valores de calidad.
Ancho completo
Mitad en escritorio
Cuadrícula de 2 columnas
Cuadrícula de 3 tarjetas
Cuadrícula de 4 tarjetas
Calculadora de sizes
Elige un diseño y unos puntos de corte para generar el atributo sizes, y luego mira qué ancho srcset por defecto descargaría probablemente una pantalla concreta.
Diseño
Punto de corte de teléfono (px)
Punto de corte de tableta (px)
Ancho de pantalla: {n}px
Densidad de píxeles
A {screen}px el hueco de la imagen mide unos {slot}px de ancho ({vw}vw). Con densidad {dpr}x necesita {need} píxeles de dispositivo, así que lo más probable es que el navegador descargue el candidato de {pick}w.
Copiar
Anchos candidatos por defecto: {list}. Los navegadores pueden elegir otro, por ejemplo cuando ya tienen en caché un archivo más grande.