Rendimiento multimedia # Cinco formas de usar imágenes en React, desde la importación estática hasta las subidas del usuario Compara importaciones estáticas, rutas públicas, URL remotas, importaciones de CSS y resultados de subidas en tiempo de ejecución en React. Publicado el 11 de agosto de 2026 ## Conclusiones clave * Las importaciones estáticas de módulos permiten que el empaquetador genere huellas digitales y analice los recursos que pertenecen al producto. * Las rutas del directorio público son adecuadas para archivos que deben conservar nombres estables u omitir el procesamiento de módulos. * Las URL remotas requieren políticas explícitas sobre hosts, caché, privacidad y fallos. «Importar una imagen» en React puede significar empaquetar un archivo fuente, hacer referencia a un recurso público, renderizar una URL remota, cargarla mediante CSS o recibirla desde un flujo de trabajo de subida. Cada vía tiene un ciclo de vida diferente. ## En esta guía 1. [Clasifica la imagen antes de elegir una ruta de importación](#import-images-in-react-section-1) 2. [Usa importaciones estáticas para los recursos bajo control de versiones](#import-images-in-react-section-2) 3. [Usa rutas públicas cuando quieras omitir el procesamiento de compilación](#import-images-in-react-section-3) 4. [Trata las URL remotas como datos de la aplicación](#import-images-in-react-section-4) 5. [Gestiona los SVG según las necesidades de confianza e interacción](#import-images-in-react-section-5) 6. [Reserva las importaciones mediante CSS para imágenes decorativas](#import-images-in-react-section-6) 7. [Previsualiza archivos locales sin confundirlos con importaciones](#import-images-in-react-section-7) 8. [Implementa las subidas de los usuarios como un pipeline de procesamiento autorizado](#import-images-in-react-section-8) 9. [Renderiza cada fuente con un diseño y una semántica estables](#import-images-in-react-section-9) 10. [Prueba el comportamiento de los recursos tanto en desarrollo como en producción](#import-images-in-react-section-10) ## Lo más importante * Las importaciones mediante CSS son adecuadas para recursos decorativos, no para contenido que necesita texto alternativo. * Las subidas de usuarios necesitan almacenamiento y procesamiento autorizados por el servidor, no una importación durante la compilación. ## Clasifica la imagen antes de elegir una ruta de importación React renderiza elementos y atributos, pero no define cómo entran los archivos JPEG, PNG o SVG en una compilación. Las importaciones estáticas, las rutas de directorios públicos, las URL remotas, las referencias CSS y los componentes de imagen del framework son contratos proporcionados por el empaquetador o el framework. Los archivos seleccionados por el usuario siguen un ciclo de vida independiente de subida durante la ejecución y no pueden importarse como módulos de código fuente. Clasifica cada imagen según su propietario, frecuencia de actualización, privacidad y función semántica. Un logotipo publicado con el código de la aplicación pertenece al grafo de compilación. El avatar de un inquilino pertenece a los datos de la aplicación y al almacenamiento persistente. Una textura decorativa puede pertenecer al CSS, mientras que la ilustración de un artículo necesita semántica HTML. Elegir según el ciclo de vida evita que las rutas de despliegue y los paquetes del cliente se conviertan accidentalmente en bases de datos de recursos. ### Propiedad del producto y vinculado a la versión Prefiere una importación estática del módulo para que la compilación pueda validar el archivo y asignarle una huella digital. ### Propiedad del producto con un nombre público estable Usa el directorio público del framework cuando un manifiesto, rastreador o sistema externo requiera esa ruta. ### Contenido administrado de forma remota Almacena una URL persistente aprobada y aplica políticas de hosts, privacidad, caché y respaldo. ### Contenido proporcionado por el usuario Usa un flujo de trabajo autenticado de subida y procesamiento y, después, conserva de forma persistente el registro de almacenamiento resultante. ## Usa importaciones estáticas para los recursos bajo control de versiones Un componente típico importa un archivo conocido y pasa el valor importado a un elemento `img` o a un componente del framework. Según el stack de herramientas, la importación puede convertirse en una URL con huella digital o en un objeto que contenga la URL y metadatos de dimensiones. Esto permite que la compilación falle si falta un archivo, lleve un seguimiento de las dependencias y actualice las claves de caché cuando cambie el contenido. Las importaciones estáticas funcionan mejor para un conjunto limitado de iconos, ilustraciones y capturas de pantalla del producto. Importar anticipadamente un catálogo multimedia completo puede ampliar el grafo de compilación y hacer que los recursos sean detectables desde rutas que nunca los renderizan. Mantén las imágenes específicas de una ruta cerca de ella y usa mecanismos dinámicos o glob compatibles con el framework solo cuando el conjunto de candidatos se conozca durante la compilación. No construyas rutas de importación arbitrarias a partir de datos ingresados por el usuario. Importar mediante el empaquetador una imagen controlada en el código fuente ``` import type { ReactNode } from 'react' import diagramUrl from './request-flow.png' export function RequestFlow(): ReactNode { return ( Request flow from the browser to object storage ) } ``` ## Usa rutas públicas cuando quieras omitir el procesamiento de compilación Los archivos de un directorio público normalmente se copian en la salida del despliegue y se solicitan mediante una ruta como `/images/logo.png`. El navegador resuelve esa cadena en tiempo de ejecución, por lo que el sistema de resolución de módulos no puede detectar un nombre de archivo mal escrito ni adjuntar los metadatos importados de sus dimensiones. Los nombres estables son útiles para favicons, manifiestos, recursos para redes sociales y archivos a los que hacen referencia sistemas externos a la compilación de JavaScript. Las rutas públicas son sensibles a las rutas base de despliegue, los proxies inversos y los prefijos de recursos. Una ruta absoluta desde la raíz puede funcionar en el dominio principal y fallar cuando la aplicación está montada en un subdirectorio. Sigue las reglas de rutas del framework en lugar de concatenar valores de `window.location`. Asigna nombres con huellas digitales a los archivos que cambian con frecuencia o establece una política de revalidación deliberada para que un despliegue no deje a los usuarios con código e imágenes en caché que no coincidan. ## Trata las URL remotas como datos de la aplicación Un valor `src` externo puede representar una imagen de un CMS, un objeto de almacenamiento o un servicio de terceros. Almacénalo como dato validado en lugar de dispersar cadenas de hosts entre los componentes. Define qué esquemas y hosts están permitidos, qué sucede cuando falta el objeto, si se requiere autenticación y cómo funciona la invalidación de la caché. Evita guardar URL firmadas que expiren en registros destinados a persistir más allá de una sesión. Los componentes de imagen del framework pueden requerir una lista de hosts remotos permitidos y añadir funciones de dimensionamiento, negociación de formatos u optimización. Esos comportamientos son características del framework, no de React, y pueden cambiar la ruta de la solicitud o el modelo de costos. Confirma si el host original o un optimizador recibe identificadores de usuario. Aplica de forma coherente Content Security Policy, la política de referentes y los requisitos de privacidad, especialmente cuando un registro no confiable puede influir en la URL. Validar una URL remota antes de renderizarla ``` import type { ReactNode } from 'react' const allowedImageHosts = new Set(['media.example.com']) interface ProductImageProps { alt: string height: number src: string width: number } export function ProductImage({ alt, height, src, width }: ProductImageProps): ReactNode { if (!URL.canParse(src)) { return null } const url = new URL(src) if (url.protocol !== 'https:' || !allowedImageHosts.has(url.hostname)) { return null } return {alt} } ``` ### Política de hosts Permite únicamente orígenes HTTPS previstos y rechaza esquemas ejecutables o de redes locales. ### Política de fallos Renderiza un marcador de posición significativo u omite los recursos multimedia opcionales sin crear un ciclo infinito de reintentos. ### Política de caché Elige claves de objeto inmutables o define cómo los objetos modificados invalidan las cachés del navegador y de los intermediarios. ### Política de privacidad Identifica qué servicio recibe la solicitud y si las imágenes privadas necesitan acceso autenticado. ## Gestiona los SVG según las necesidades de confianza e interacción Renderizar un SVG mediante `img` lo trata como una imagen externa y mantiene sus elementos internos fuera del DOM de la aplicación. Importar un SVG como componente de React, cuando la compilación lo admite, expone rutas y atributos para aplicar estilos y animaciones, pero aumenta el marcado y vincula el código fuente a un plugin específico del compilador. Por lo tanto, hacer referencia a un archivo SVG e importarlo como componente son contratos diferentes. No conviertas un SVG subido y no confiable en marcado en línea de la aplicación. Un SVG puede contener funciones activas o externas, y la extensión del nombre de archivo por sí sola no garantiza que su contenido sea seguro. Sanéalo con una política diseñada para el conjunto previsto de funciones SVG, proporciona los archivos riesgosos como descargas cuando corresponda y aplica encabezados de respuesta restrictivos. Para iconos sencillos del producto, prefiere el sistema de iconos establecido de la aplicación en lugar de crear otro cargador. ## Reserva las importaciones mediante CSS para imágenes decorativas Un módulo CSS o una hoja de estilos puede hacer referencia a un fondo mediante `url()`, lo que permite que el empaquetador genere una huella digital de un recurso local. Esto es adecuado para texturas, máscaras y capas decorativas. No sustituye a un elemento `img` cuando los lectores necesitan texto alternativo, dimensiones intrínsecas, controles de carga específicos para imágenes o la posibilidad de guardar e inspeccionar contenido significativo. Recuerda que el descubrimiento mediante CSS puede retrasar una imagen importante hasta que la hoja de estilos se descargue y se evalúen sus reglas. Una regla oculta puede incluirse en la compilación aunque ninguna ruta la use, según el comportamiento del empaquetador. Mantén los recursos decorativos junto a su componente, revisa el resultado generado y prueba los estados de fallo y de alto contraste. El texto y los controles esenciales deben permanecer en el árbol de React en lugar de estar integrados en un fondo. ## Previsualiza archivos locales sin confundirlos con importaciones Un archivo seleccionado mediante un campo de entrada o una zona de arrastre es un `File` del navegador, normalmente respaldado por un Blob local. Crea una URL de objeto temporal para obtener una vista previa o usa una API de decodificación, y revoca cada URL de objeto cuando se sustituya la vista previa o se elimine el componente. La URL de la vista previa es local a la sesión y nunca debe almacenarse como si fuera la URL de un recurso público. Valida el archivo candidato antes de realizar tareas costosas de vista previa. Comprueba el tipo permitido, el límite de bytes y, después de decodificarlo, las dimensiones en píxeles. El tipo MIME declarado y la extensión son indicios, no pruebas. Mantén un estado de error claro y controles de selección accesibles mediante el teclado. Las imágenes grandes pueden agotar la memoria al decodificarse aunque su tamaño comprimido en bytes parezca aceptable, por lo que las comprobaciones del cliente deben complementar la validación del servidor, no sustituirla. ## Implementa las subidas de los usuarios como un pipeline de procesamiento autorizado Las imágenes seleccionadas por los usuarios son objetos `File`, no importaciones. Muéstralas en una vista previa mediante una URL de objeto y luego súbelas a través de un endpoint del backend o de una solicitud de subida directa con una firma de alcance limitado. Mantén las credenciales reutilizables fuera del cliente, autoriza el destino y el tipo de contenido esperado, aplica límites de bytes y píxeles decodificados, y trata el tipo MIME informado por el navegador como un indicio, no como una prueba. Después de que el backend valide y procese una subida, guarda de forma persistente una clave de objeto o una URL de entrega propia junto con las dimensiones, el tipo MIME detectado, la propiedad y el ID del registro de la aplicación. Las URL temporales de vista previa y las URL de procesamiento de corta duración pertenecen únicamente a la interacción actual. React renderiza los datos resultantes; la base de datos, la política de almacenamiento y la capa de entrega controlan su ciclo de vida. ### Navegador Recopila archivos, muestra el progreso, permite cancelar y solicita una subida de corta duración autorizada por el servidor. ### Procesamiento Crea únicamente derivados aprobados y rechaza los recursos multimedia no compatibles antes de que entren en el estado normal de la aplicación. ### Almacenamiento Exporta los resultados a un destino propiedad de la aplicación con ajustes deliberados de acceso y ciclo de vida. ### Base de datos Registra identificadores de objeto estables y metadatos en lugar de URL temporales de vista previa o procesamiento. ## Renderiza cada fuente con un diseño y una semántica estables Independientemente de cómo se haya obtenido `src`, las imágenes significativas necesitan un uso adecuado de `alt`. Describe la función de la imagen en contexto, usa un valor vacío para los elementos `img` genuinamente decorativos y evita repetir los textos descriptivos adyacentes. Las imágenes utilizadas como enlaces necesitan texto alternativo que comunique el destino o la acción. Una imagen CSS no tiene un canal semántico equivalente. Proporciona valores intrínsecos de `width` y `height`, o usa un componente del framework que reserve una relación de aspecto equivalente, para que la carga no desplace el contenido circundante. El CSS responsivo solo cambia el tamaño de visualización; no evita la descarga de un original sobredimensionado. Usa candidatos responsivos cuando estén disponibles, evita la carga diferida de la imagen principal que aparece en la parte visible inicial y define un respaldo deliberado cuando no se pueda decodificar un objeto remoto. ## Prueba el comportamiento de los recursos tanto en desarrollo como en producción Los servidores de desarrollo suelen admitir rutas permisivas y omitir el hashing, la optimización y el comportamiento de las rutas base utilizados en producción. Ejecuta una compilación de producción e inspecciona las URL de recursos emitidas, las descargas por ruta, los errores de hosts remotos y los mapas de código fuente. Accede directamente a rutas anidadas, actualízalas y prueba la aplicación con la misma subruta o configuración de proxy utilizada en el despliegue. Las pruebas de componentes deben comprobar los nombres accesibles y el comportamiento de respaldo, mientras que las pruebas en el navegador deben abarcar una carga correcta, un recurso ausente, una carga lenta y un archivo de usuario rechazado. Supervisa las respuestas de imágenes rotas y los errores del optimizador después del lanzamiento. Mantén las subidas idempotentes cuando puedan producirse reintentos, elimina las vistas previas temporales abandonadas y asegúrate de que eliminar un registro de la aplicación active el ciclo de vida de almacenamiento previsto, en lugar de limitarse a ocultar el elemento de React. ## Detalles técnicos que conviene conocer * Una importación estática permite que un empaquetador genere la huella digital de un recurso conocido, lo optimice y lo verifique durante la compilación, mientras que una cadena de ruta pública solo se resuelve cuando el navegador la solicita. * Los archivos seleccionados por el usuario son objetos Blob locales, no importaciones de módulos. Para previsualizarlos se necesita una URL de objeto o una API de decodificación, y para subirlos se necesita un flujo de trabajo de red explícito. * Los componentes de imagen del framework pueden añadir políticas de dimensionamiento, optimización y carga, pero su comportamiento y sus listas de hosts remotos permitidos son contratos del framework, no características de React. * Importar de inmediato muchas imágenes grandes puede agregarlas al grafo de compilación y a la ruta del paquete inicial, aunque los usuarios nunca las vean; la detección por ruta y la carga diferida son importantes. * El elemento img sigue necesitando dimensiones intrínsecas y un comportamiento significativo del texto alternativo, sin importar si su src proviene de una importación, una URL, un Blob o un optimizador del framework. * Las subidas de SVG no confiables no deben renderizarse como marcado común integrado en la aplicación sin un saneamiento deliberado y una política de seguridad de contenido. ## Un enfoque práctico 1. 1\ Clasifica cada imagen según su propietario, frecuencia de actualización, privacidad y si constituye contenido semántico. 2. 2\ Usa la ruta de recursos nativa del framework para los archivos propios del producto. 3. 3\ Usa un pipeline de subida y un registro persistente en la base de datos para los archivos que pertenecen al usuario. 4. 4\ Prueba los recursos ausentes, las dimensiones del diseño, el texto alternativo, la caché y las rutas base de despliegue. Un flujo de trabajo multimedia de cuatro etapas ## Límite de la arquitectura React por sí mismo no define la semántica de importación de imágenes. Los empaquetadores y frameworks determinan cómo se comportan los recursos estáticos, las rutas públicas, las URL remotas y los componentes de imagen optimizados, mientras que la aplicación controla las políticas de subida y entrega. ## Preguntas frecuentes ### ¿React requiere importar las imágenes? No. React acepta un valor `src` como el HTML normal. La herramienta de compilación o el framework proporcionan las importaciones estáticas, los directorios públicos y los componentes de imagen optimizados. Elige el mecanismo que corresponda con la propiedad del recurso y su ciclo de vida de despliegue. ### ¿Cuándo debe colocarse una imagen en el directorio público? Usa el directorio público cuando el archivo necesite una ruta predecible o deba omitir el procesamiento de módulos, como un recurso de manifiesto. Usa una importación estática para la mayoría de los archivos propios de un componente, ya que la validación y la generación de huellas digitales durante la compilación suelen ser útiles. ### ¿Sigue siendo necesario `require()` para las imágenes en React? Por lo general, no en aplicaciones modernas basadas en ESM. Prefiere la sintaxis de importación y las convenciones para recursos que documente el empaquetador o framework activo. Conserva `require()` solo cuando un stack de herramientas CommonJS existente dependa explícitamente de esta función. ### ¿Cómo debe una aplicación de React previsualizar una imagen subida? Trata el valor seleccionado como un `File`, valídalo y crea una URL de objeto temporal o una vista previa decodificada. Revoca la URL de objeto cuando ya no se utilice. Sube el original mediante un flujo de trabajo autorizado y sustituye la vista previa por un resultado almacenado de forma persistente. ### ¿Puede guardarse la URL temporal del resultado de una subida como URL permanente de la imagen? Puede usarse mientras se gestiona la subida actual, pero los registros de larga duración deben contener una clave de objeto o una URL administrada por un almacenamiento propiedad de la aplicación. Las URL de Blob, las URL firmadas y las URL de procesamiento temporales caducan o están vinculadas a una sesión. Conserva las dimensiones útiles, el tipo MIME, la propiedad y la procedencia junto a la ubicación persistente. Rendimiento multimedia ## Continúa con guías relacionadas * [Añadir imágenes e insignias a un README de GitHub: cuatro formas](/es/guides/images-in-github-readmes.md)\ Agrega imágenes a un README de GitHub mediante archivos del repositorio, adjuntos de incidencias, URL sin procesar, HTML o recursos generados. * [Cinco mejores prácticas para imágenes de fondo en HTML y CSS](/es/guides/html-background-image-best-practices.md)\ Cinco prácticas para imágenes de fondo CSS que equilibran la composición, la accesibilidad y el rendimiento de la página. * [Seis formas confiables de guardar imágenes en Python](/es/guides/save-images-in-python.md)\ Guarda imágenes desde bytes, URL, Pillow, OpenCV, subidas y resultados de procesamiento gestionado sin perder el manejo de errores. * [Ocho prácticas para optimizar el SEO de imágenes](/es/guides/image-seo-optimization.md)\ Ocho prácticas de SEO para imágenes sobre semántica, dimensiones, formatos, rendimiento, descubrimiento y medición. * [Cómo servir imágenes responsivas desde una sola URL](/es/guides/serve-responsive-images-from-one-url.md)\ Genera cada tamaño de imagen desde una URL canónica, almacena los resultados en caché perimetral y mantén estable el costo de codificación al crecer el tráfico.