Medienperformance # React-Bilder: fünf Wege vom statischen Import zum Nutzer-Upload Vergleichen Sie statische Importe, öffentliche Pfade, externe URLs, CSS-Importe und Ergebnisse von Laufzeit-Uploads in React. Veröffentlicht am 11. August 2026 ## Wichtigste Erkenntnisse * Statische Modulimporte ermöglichen es dem Bundler, produkteigene Assets mit Fingerprints zu versehen und zu analysieren. * Pfade öffentlicher Verzeichnisse eignen sich für Dateien, die stabile Namen behalten oder die Modulverarbeitung umgehen müssen. * Externe URLs erfordern explizite Richtlinien für Hosts, Caching, Datenschutz und Fehlerfälle. „Ein Bild importieren“ kann in React bedeuten, eine Quelldatei zu bündeln, auf ein öffentliches Asset zu verweisen, eine externe URL zu rendern, ein Bild über CSS zu laden oder es aus einem Upload-Workflow zu empfangen. Jeder dieser Wege hat einen anderen Lebenszyklus. ## In diesem Leitfaden 1. [Bild vor der Wahl des Importpfads klassifizieren](#import-images-in-react-section-1) 2. [Statische Importe für quellcodeverwaltete Assets verwenden](#import-images-in-react-section-2) 3. [Öffentliche Pfade verwenden, wenn die Build-Verarbeitung bewusst umgangen wird](#import-images-in-react-section-3) 4. [Externe URLs als Anwendungsdaten behandeln](#import-images-in-react-section-4) 5. [SVG gemäß Vertrauensniveau und Interaktionsanforderungen handhaben](#import-images-in-react-section-5) 6. [CSS-Importe dekorativen Bildern vorbehalten](#import-images-in-react-section-6) 7. [Lokale Dateien in der Vorschau anzeigen, ohne sie mit Importen zu verwechseln](#import-images-in-react-section-7) 8. [Nutzer-Uploads als autorisierte Verarbeitungspipeline aufbauen](#import-images-in-react-section-8) 9. [Jede Quelle mit stabilem Layout und stabiler Semantik rendern](#import-images-in-react-section-9) 10. [Asset-Verhalten in Entwicklung und Produktion testen](#import-images-in-react-section-10) ## Worauf es besonders ankommt * CSS-Importe eignen sich für dekorative Assets, nicht für Inhalte, die Alternativtext benötigen. * Nutzer-Uploads benötigen serverseitig autorisierten Speicher und Verarbeitung statt eines Imports zur Build-Zeit. ## Bild vor der Wahl des Importpfads klassifizieren React rendert Elemente und Attribute. Es legt nicht fest, wie JPEG-, PNG- oder SVG-Dateien in einen Build gelangen. Statische Importe, Pfade öffentlicher Verzeichnisse, Remote-URLs, CSS-Referenzen und Bildkomponenten von Frameworks sind vom Bundler oder Framework bereitgestellte Schnittstellen. Von Nutzern ausgewählte Dateien durchlaufen einen separaten Upload-Lebenszyklus zur Laufzeit und können nicht als Quellmodule importiert werden. Klassifizieren Sie jedes Bild nach Eigentümer, Aktualisierungshäufigkeit, Datenschutz und semantischer Rolle. Ein Logo, das zusammen mit dem Anwendungscode veröffentlicht wird, gehört in den Build-Graphen. Der Avatar eines Mandanten gehört zu den Anwendungsdaten und in einen dauerhaften Speicher. Eine dekorative Textur kann in CSS gehören, während eine Artikelillustration eine semantische Auszeichnung in HTML benötigt. Eine am Lebenszyklus ausgerichtete Entscheidung verhindert, dass Bereitstellungspfade und Client-Bundles unbeabsichtigt zu Asset-Datenbanken werden. ### Produkteigen und an ein Release gebunden Bevorzugen Sie einen statischen Modulimport, damit der Build die Datei validieren und mit einem Fingerprint versehen kann. ### Produkteigen mit stabilem öffentlichem Namen Verwenden Sie das öffentliche Verzeichnis des Frameworks, wenn ein Manifest, Crawler oder externes System diesen Pfad benötigt. ### Extern verwaltete Inhalte Speichern Sie eine freigegebene dauerhafte URL und setzen Sie Richtlinien für Host, Datenschutz, Caching und Fallback durch. ### Von Nutzern bereitgestellte Inhalte Verwenden Sie einen authentifizierten Upload- und Verarbeitungsworkflow und speichern Sie anschließend den resultierenden Speicherdatensatz dauerhaft. ## Statische Importe für quellcodeverwaltete Assets verwenden Eine typische Komponente importiert eine bekannte Datei und übergibt den importierten Wert an ein `img`-Element oder eine Framework-Komponente. Je nach Toolchain kann aus dem Import eine URL mit Fingerprint oder ein Objekt mit Metadaten zu URL und Abmessungen werden. So kann der Build bei einer fehlenden Datei fehlschlagen, Abhängigkeiten nachverfolgen und Cache-Schlüssel aktualisieren, wenn sich Inhalte ändern. Statische Importe eignen sich am besten für eine begrenzte Menge von Symbolen, Illustrationen und Produkt-Screenshots. Wird ein vollständiger Medienkatalog sofort importiert, kann dies den Build-Graphen vergrößern und Medien über Routen auffindbar machen, die sie nie rendern. Speichern Sie routenspezifische Bilder nahe bei der jeweiligen Route und verwenden Sie vom Framework unterstützte dynamische Mechanismen oder Glob-Mechanismen nur, wenn die Menge der möglichen Dateien zur Build-Zeit bekannt ist. Erzeugen Sie keine beliebigen Importpfade aus Nutzereingaben. Ein versionsverwaltetes Bild über den Bundler importieren ``` import type { ReactNode } from 'react' import diagramUrl from './request-flow.png' export function RequestFlow(): ReactNode { return ( Request flow from the browser to object storage ) } ``` ## Öffentliche Pfade verwenden, wenn die Build-Verarbeitung bewusst umgangen wird Dateien in einem öffentlichen Verzeichnis werden normalerweise in die Bereitstellungsausgabe kopiert und über einen Pfad wie `/images/logo.png` angefordert. Der Browser löst diese Zeichenfolge zur Laufzeit auf. Deshalb kann der Modul-Resolver weder einen falsch geschriebenen Dateinamen erkennen noch importierte Metadaten zu den Abmessungen anfügen. Stabile Namen eignen sich für Favicons, Manifeste, Inhalte für soziale Medien und Dateien, auf die Systeme außerhalb des JavaScript-Builds verweisen. Öffentliche Pfade reagieren empfindlich auf Basispfade der Bereitstellung, Reverse-Proxys und Asset-Präfixe. Ein absoluter Root-Pfad kann auf der Hauptdomain funktionieren und fehlschlagen, wenn die Anwendung unterhalb eines Unterverzeichnisses eingebunden ist. Befolgen Sie die Pfadregeln des Frameworks, statt `window.location`-Werte zu verketten. Versehen Sie häufig geänderte Dateien mit Fingerprint-Namen oder legen Sie eine gezielte Richtlinie zur erneuten Validierung fest, damit Nutzer nach einer Bereitstellung nicht mit zwischengespeichertem Code und dazu nicht passenden Bildern zurückbleiben. ## Externe URLs als Anwendungsdaten behandeln Ein externer `src`-Wert kann ein CMS-Bild, ein Speicherobjekt oder einen Drittanbieterdienst darstellen. Speichern Sie ihn als validierte Daten, statt Host-Zeichenfolgen über Komponenten zu verteilen. Legen Sie fest, welche Schemata und Hosts zulässig sind, was bei einem fehlenden Objekt geschieht, ob eine Authentifizierung erforderlich ist und wie die Cache-Invalidierung funktioniert. Speichern Sie keine ablaufenden signierten URLs in Datensätzen, die über eine Sitzung hinaus bestehen sollen. Bildkomponenten von Frameworks können eine Positivliste für Remote-Hosts erfordern und Funktionen für Größenfestlegung, Formataushandlung oder Optimierung ergänzen. Dieses Verhalten beruht auf Funktionen des Frameworks, nicht auf React, und kann den Anfragepfad oder das Kostenmodell verändern. Prüfen Sie, ob der ursprüngliche Host oder ein Optimierungsdienst Nutzerkennungen empfängt. Wenden Sie Content Security Policy, Referrer-Richtlinie und Datenschutzanforderungen einheitlich an, insbesondere wenn ein nicht vertrauenswürdiger Datensatz die URL beeinflussen kann. Eine Remote-URL vor dem Rendern validieren ``` 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} } ``` ### Host-Richtlinie Lassen Sie nur erwartete HTTPS-Ursprünge zu und lehnen Sie ausführbare Schemata sowie Schemata für lokale Netzwerke ab. ### Fehlerrichtlinie Rendern Sie einen aussagekräftigen Platzhalter oder lassen Sie optionale Medien weg, ohne eine Endlosschleife für erneute Versuche zu erzeugen. ### Cache-Richtlinie Wählen Sie unveränderliche Objektschlüssel oder legen Sie fest, wie geänderte Objekte die Caches von Browsern und Vermittlungsstellen invalidieren. ### Datenschutzrichtlinie Stellen Sie fest, welcher Dienst die Anfrage erhält und ob private Bilder einen authentifizierten Zugriff benötigen. ## SVG gemäß Vertrauensniveau und Interaktionsanforderungen handhaben Wird eine SVG-Datei über `img` gerendert, gilt sie als externes Bild und ihre internen Elemente bleiben außerhalb des Anwendungs-DOM. Wird eine SVG-Datei als React-Komponente importiert, sofern der Build dies unterstützt, sind Pfade und Attribute für Styling und Animation zugänglich. Dies vergrößert jedoch das Markup und bindet die Quelldatei an ein bestimmtes Compiler-Plug-in. Der Verweis auf eine SVG-Datei und ihr Import als Komponente sind daher unterschiedliche Schnittstellen. Wandeln Sie eine nicht vertrauenswürdige hochgeladene SVG-Datei nicht in Inline-Markup der Anwendung um. SVG kann aktive oder externe Funktionen enthalten, und eine Dateiendung allein macht den Inhalt nicht sicher. Bereinigen Sie die Datei anhand einer Richtlinie, die für den vorgesehenen SVG-Funktionsumfang ausgelegt ist, stellen Sie riskante Dateien gegebenenfalls als Downloads bereit und verwenden Sie restriktive Antwort-Header. Bevorzugen Sie für einfache Produktsymbole das etablierte Symbolsystem der Anwendung, statt einen weiteren Loader einzuführen. ## CSS-Importe dekorativen Bildern vorbehalten Ein CSS-Modul oder Stylesheet kann mit `url()` auf einen Hintergrund verweisen, sodass der Bundler eine lokale Mediendatei mit einem Fingerprint versehen kann. Dies eignet sich für Texturen, Masken und dekorative Ebenen. Es ist kein Ersatz für ein `img`-Element, wenn Leser Alternativtext, intrinsische Abmessungen, bildspezifische Steuerelemente für das Laden oder die Möglichkeit benötigen, semantisch relevante Inhalte zu speichern und zu untersuchen. Beachten Sie, dass die Erkennung über CSS das Laden eines wichtigen Bildes verzögern kann, bis das Stylesheet heruntergeladen und zugeordnet wurde. Je nach Verhalten des Bundlers kann eine ausgeblendete Regel selbst dann in den Build gelangen, wenn keine Route sie verwendet. Speichern Sie dekorative Medien zusammen mit der zugehörigen Komponente, prüfen Sie die erzeugte Ausgabe und testen Sie Fehlerzustände sowie Darstellungen mit hohem Kontrast. Wesentliche Texte und Steuerelemente müssen im React-Baum verbleiben, statt in einen Hintergrund eingebettet zu werden. ## Lokale Dateien in der Vorschau anzeigen, ohne sie mit Importen zu verwechseln Eine über ein Eingabefeld oder eine Dropzone ausgewählte Datei ist ein `File` des Browsers, dem normalerweise ein lokales Blob zugrunde liegt. Erstellen Sie für eine Vorschau eine temporäre Objekt-URL oder verwenden Sie eine API zum Decodieren. Widerrufen Sie jede Objekt-URL, sobald die Vorschau ersetzt oder die Komponente entfernt wird. Die Vorschau-URL gilt nur für die aktuelle Sitzung und darf niemals wie eine öffentliche Asset-URL gespeichert werden. Validieren Sie den Kandidaten, bevor Sie eine aufwendige Vorschau erzeugen. Prüfen Sie den zulässigen Typ, das Byte-Limit und nach dem Decodieren die Pixelabmessungen. Der angegebene MIME-Typ und die Dateierweiterung sind Hinweise, keine Belege. Sorgen Sie für einen eindeutigen Fehlerzustand und Auswahlsteuerelemente, die per Tastatur zugänglich sind. Große Bilder können beim Decodieren den Arbeitsspeicher erschöpfen, selbst wenn ihre komprimierte Bytegröße akzeptabel erscheint. Clientseitige Prüfungen sollten daher die serverseitige Validierung ergänzen, nicht ersetzen. ## Nutzer-Uploads als autorisierte Verarbeitungspipeline aufbauen Von Nutzern ausgewählte Bilder sind `File`-Objekte, keine Importe. Zeigen Sie mit einer Objekt-URL eine Vorschau an und laden Sie sie anschließend über einen Backend-Endpunkt oder eine eng begrenzte, signierte Direkt-Upload-Anfrage hoch. Halten Sie wiederverwendbare Zugangsdaten vom Client fern, autorisieren Sie das Ziel und den erwarteten Inhaltstyp, setzen Sie Byte- und Grenzwerte für decodierte Pixel durch und behandeln Sie den vom Browser gemeldeten MIME-Typ als Hinweis, nicht als Beleg. Nachdem das Backend einen Upload validiert und verarbeitet hat, speichern Sie dauerhaft einen beständigen Objektschlüssel oder eine eigene Auslieferungs-URL zusammen mit den Abmessungen, dem erkannten MIME-Typ, den Eigentumsangaben und der ID des Anwendungsdatensatzes. Temporäre Vorschau-URLs und kurzlebige Verarbeitungs-URLs gehören ausschließlich zur aktuellen Interaktion. React rendert die resultierenden Daten; Datenbank, Speicherrichtlinie und Auslieferungsschicht verwalten deren Lebenszyklus. ### Webbrowser Dateien erfassen, Fortschritt anzeigen, Abbrechen ermöglichen und einen kurzlebigen, serverseitig autorisierten Upload anfordern. ### Verarbeitung Nur genehmigte Derivate erstellen und nicht unterstützte Medien ablehnen, bevor sie in den regulären Anwendungszustand gelangen. ### Speicher Ergebnisse an ein anwendungseigenes Ziel exportieren, dessen Zugriffs- und Lebenszykluseinstellungen bewusst festgelegt sind. ### Datenbank Stabile Objektkennungen und Metadaten statt temporärer Vorschau- oder Verarbeitungs-URLs erfassen. ## Jede Quelle mit stabilem Layout und stabiler Semantik rendern Unabhängig davon, wie `src` bezogen wurde, benötigen inhaltlich relevante Bilder ein angemessenes `alt`-Verhalten. Beschreiben Sie die Funktion des Bildes im jeweiligen Kontext, verwenden Sie für tatsächlich dekorative `img`-Elemente einen leeren Wert und wiederholen Sie keine benachbarten Bildunterschriften. Als Links verwendete Bilder benötigen einen Alternativtext, der das Ziel oder die Aktion vermittelt. Für ein CSS-Bild gibt es keinen gleichwertigen semantischen Kanal. Geben Sie die intrinsischen Werte für `width` und `height` an oder verwenden Sie eine Framework-Komponente, die ein entsprechendes Seitenverhältnis reserviert, damit sich umgebende Inhalte beim Laden nicht verschieben. Responsives CSS ändert nur die Darstellungsgröße; es verhindert nicht, dass ein übergroßes Original heruntergeladen wird. Verwenden Sie verfügbare responsive Kandidaten, vermeiden Sie Lazy Loading für das primäre Bild im ohne Scrollen sichtbaren Bereich und definieren Sie einen gezielten Fallback für den Fall, dass ein Remote-Objekt nicht decodiert werden kann. ## Asset-Verhalten in Entwicklung und Produktion testen Entwicklungsserver stellen Pfade oft großzügig bereit und überspringen das Hashing, die Optimierung und das Basispfadverhalten der Produktionsumgebung. Führen Sie einen Produktions-Build aus und prüfen Sie ausgegebene Asset-URLs, Downloads auf Routenebene, Fehler bei Remote-Hosts und Source Maps. Rufen Sie verschachtelte Routen direkt auf, aktualisieren Sie sie und testen Sie die Anwendung hinter demselben Unterpfad oder derselben Proxy-Konfiguration wie bei der Bereitstellung. Komponententests sollten zugängliche Namen und das Fallback-Verhalten prüfen. Browsertests sollten dagegen erfolgreiches Laden, ein fehlendes Asset, langsames Laden und eine abgelehnte Nutzerdatei abdecken. Überwachen Sie nach der Veröffentlichung Antworten für beschädigte Bilder und Optimierungsfehler. Sorgen Sie dafür, dass Uploads bei möglichen Wiederholungsversuchen idempotent bleiben, entfernen Sie aufgegebene temporäre Vorschauen und stellen Sie sicher, dass das Löschen eines Anwendungsdatensatzes den vorgesehenen Speicherlebenszyklus auslöst, statt nur das React-Element auszublenden. ## Wissenswerte technische Details * Bei einem statischen Import kann ein Bundler ein bekanntes Asset zur Build-Zeit mit einem Fingerprint versehen, optimieren und überprüfen. Eine Zeichenfolge mit einem öffentlichen Pfad wird dagegen erst aufgelöst, wenn der Browser sie anfordert. * Von Nutzern ausgewählte Dateien sind lokale Blob-Objekte und keine Modulimporte. Für ihre Vorschau ist eine Objekt-URL oder Decode-API erforderlich, für ihren Upload ein expliziter Netzwerk-Workflow. * Bildkomponenten von Frameworks können Größenangaben, Optimierung und Laderichtlinien ergänzen. Ihr Verhalten und ihre Positivlisten für Remote-Hosts sind jedoch Framework-Vorgaben und keine React-Funktionen. * Werden viele große Bilder vorab importiert, können sie dem Build-Graphen und dem Pfad des anfänglichen Bundles hinzugefügt werden, selbst wenn Nutzer sie nie ansehen. Daher sind die Erkennung auf Routenebene und verzögertes Laden wichtig. * Das img-Element benötigt weiterhin intrinsische Abmessungen und ein sinnvolles Alternativtextverhalten, unabhängig davon, ob sein src aus einem Import, einer URL, einem Blob oder einem Framework-Optimierer stammt. * Nicht vertrauenswürdige SVG-Uploads sollten ohne gezielte Bereinigung und Content-Security-Policy nicht als gewöhnliches Inline-Markup der Anwendung gerendert werden. ## Ein praxisnaher Ansatz 1. 1\ Klassifizieren Sie jedes Bild nach Eigentümer, Aktualisierungshäufigkeit, Datenschutz und danach, ob es semantischer Inhalt ist. 2. 2\ Verwenden Sie für Dateien im Eigentum des Produkts den nativen Asset-Pfad des Frameworks. 3. 3\ Verwenden Sie für Dateien im Eigentum der Nutzer eine Upload-Pipeline und einen dauerhaft gespeicherten Datenbankeintrag. 4. 4\ Testen Sie fehlende Assets, Layoutabmessungen, Alternativtext, Caching und Basispfade für die Bereitstellung. Ein vierstufiger Medienworkflow ## Architekturgrenze React selbst definiert keine Semantik für Bildimporte. Bundler und Frameworks bestimmen das Verhalten statischer Assets, öffentlicher Pfade, externer URLs und optimierter Bildkomponenten, während die Anwendung für die Upload- und Auslieferungsrichtlinien verantwortlich ist. ## Häufig gestellte Fragen ### Müssen Bilder in React importiert werden? Nein. React akzeptiert wie normales HTML einen `src`-Wert. Statische Importe, öffentliche Verzeichnisse und optimierte Bildkomponenten werden vom Build-Tool oder Framework bereitgestellt. Wählen Sie den Mechanismus passend zu den Eigentumsverhältnissen und dem Deployment-Lebenszyklus des Assets. ### Wann sollte ein Bild im öffentlichen Verzeichnis liegen? Verwenden Sie das öffentliche Verzeichnis, wenn die Datei einen vorhersehbaren Pfad benötigt oder die Modulverarbeitung umgehen muss, etwa bei einem Manifest-Asset. Für die meisten Dateien, die zu einer Komponente gehören, eignet sich ein statischer Import, da Validierung und Fingerprinting zur Build-Zeit meist hilfreich sind. ### Ist `require()` für React-Bilder weiterhin erforderlich? In modernen ESM-basierten Anwendungen in der Regel nicht. Bevorzugen Sie die Importsyntax und Asset-Konventionen, die der verwendete Bundler oder das Framework dokumentiert. Behalten Sie `require()` nur bei, wenn eine bestehende CommonJS-Toolchain ausdrücklich davon abhängt. ### Wie sollte eine React-App eine Vorschau eines hochgeladenen Bildes anzeigen? Behandeln Sie den ausgewählten Wert als `File`, validieren Sie ihn und erstellen Sie eine temporäre Objekt-URL oder eine decodierte Vorschau. Widerrufen Sie die Objekt-URL, sobald sie nicht mehr verwendet wird. Laden Sie das Original über einen autorisierten Workflow hoch und ersetzen Sie die Vorschau durch ein dauerhaft gespeichertes Ergebnis. ### Kann die temporäre Ergebnis-URL eines Uploads als dauerhafte Bild-URL gespeichert werden? Sie kann während der Verarbeitung des aktuellen Uploads verwendet werden, doch langlebige Datensätze sollten einen Objektschlüssel oder eine URL enthalten, die einem anwendungseigenen Speicher unterliegt. Blob-URLs, signierte URLs und temporäre Verarbeitungs-URLs laufen ab oder sind sitzungsgebunden. Speichern Sie nützliche Abmessungen, MIME-Typ, Eigentumsangaben und Herkunft zusammen mit dem dauerhaften Speicherort. Medienperformance ## Mit verwandten Leitfäden fortfahren * [Vier Wege für Bilder und Badges in GitHub-READMEs](/de/guides/images-in-github-readmes.md)\ Fügen Sie Bilder über Repository-Dateien, Issue-Anhänge, Raw-URLs, HTML oder generierte Assets zu einem GitHub-README hinzu. * [Fünf bewährte Verfahren für HTML- und CSS-Hintergrundbilder](/de/guides/html-background-image-best-practices.md)\ Fünf bewährte Verfahren für CSS-Hintergrundbilder, die Komposition, Barrierefreiheit und Seitenleistung ausgewogen berücksichtigen. * [Sechs zuverlässige Wege, Bilder in Python zu speichern](/de/guides/save-images-in-python.md)\ Bilder aus Bytes, URLs, Pillow, OpenCV, Uploads und verwalteten Verarbeitungsergebnissen speichern, ohne die Fehlerbehandlung zu beeinträchtigen. * [Acht Verfahren zur Bild-SEO-Optimierung](/de/guides/image-seo-optimization.md)\ Acht Bild-SEO-Verfahren für Semantik, Abmessungen, Formate, Leistung, Auffindbarkeit und Erfolgsmessung. * [Responsive Bilder über eine einzige URL ausliefern](/de/guides/serve-responsive-images-from-one-url.md)\ Leiten Sie jede Bildgröße aus einer kanonischen URL ab, cachen Sie die Ergebnisse am Edge und halten Sie die Encoding-Kosten trotz wachsendem Traffic stabil.