Einmal hochladen, für immer transformieren

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Die meisten Bild-Pipelines gehen beim Upload eine Wette ein: Sie erzeugen das Thumbnail sowie die mittlere, die große und die WebP-Variante und speichern sie neben dem Original. Wenn das Design eine quadratische Karte ergänzt oder AVIF möchte, führen Sie eine weitere Stapelverarbeitung über die Bibliothek aus.

Mit Transloadit Storage und dem Smart CDN behalten Sie das Original und beschreiben das Derivat in einer URL. Die erste Anfrage rendert es; nachfolgende Anfragen können das gecachte Ergebnis nutzen. Eine neue Größe oder ein neuer Zuschnitt erfordert weder einen erneuten Upload noch eine Migration der gesamten Bibliothek.

Speichern wir ein Foto und zeigen es als WebP-Karte, als quadratisches AVIF-Bild und als breiten JPEG-Zuschnitt an. Sie benötigen dafür weder ein eigenes Template noch die AWS CLI oder ein Frontend-Framework.

Transloadit Storage befindet sich in einer privaten Vorschauphase. Bitten Sie uns, es für Ihren Workspace freizuschalten. Für dieses Beispiel benötigen Sie außerdem Node.js 24.15+ oder 26+.

Ausprobieren

npx @transloadit/node@latest init upload-once my-gallery
cd my-gallery
npm run demo

Der Initializer erstellt ein neues Verzeichnis mit kompatiblen Abhängigkeiten, einem Beispielfoto und einer kleinen Datei demo.ts. Er lädt nichts hoch und verändert kein bestehendes Projekt. Die Demo öffnet bei Bedarf die Anmeldung im Browser, prüft den Storage-Zugriff und lädt das Foto hoch. Öffnen Sie gallery.html, um die drei Varianten zu sehen.

Wählen Sie auf der Freigabeseite den gewünschten Workspace. Wenn Sie ein anderes Konto benötigen, öffnen Sie den Anmeldelink in einem privaten Browserfenster, damit Sie Ihre aktuelle Console-Sitzung behalten können.

Das vollständige Beispiel samt README⁠ erscheint mit dem SDK-Release. Das generierte Projekt legt diese Version fest, und Sie können seinen Quellcode bearbeiten.

Ausgabe ändern, Original behalten

Ganz oben in demo.ts legt variants für jede Ausgabe Breite, Höhe, Format und Strategie für die Größenänderung fest. Ändern Sie eine Breite oder einen Zuschnitt und führen Sie npm run demo erneut aus. Die CLI verwendet den gespeicherten Beleg des passenden Originals wieder, statt es erneut hochzuladen, und erzeugt dann neue URLs für die Varianten. Im Terminal wird angezeigt, ob das Foto hochgeladen oder wiederverwendet wurde.

So probieren Sie es mit Ihrem eigenen Foto aus:

npm run demo -- ./your-photo.jpg

storage store --hashed verwendet einen inhaltsadressierten Dateinamen und speichert den Asset-/Versionsbeleg in transloadit.images.json. Bewahren Sie diesen Katalog auf: Damit kann die CLI wiederholte Uploads überspringen. Die README beschreibt das Verhalten beim Überschreiben und bei der Wiederherstellung, falls ein Upload nicht sauber abgeschlossen wird.

auth smart-cdn signiert URLs für die veröffentlichte Pipeline builtin/storage-preview@0.0.3. In diesen URLs legen w und h die Ausgabebox fest, f wählt das Format und q bestimmt die Qualität. pad passt das gesamte Bild in die Box ein; fillcrop füllt sie durch Zuschneiden aus. Das Beispiel gibt beide Abmessungen an.

Die resultierende Seite enthält gewöhnliche Bildelemente, die direkt auf das Smart CDN verweisen. Ihre Anwendung leitet keine Bild-Bytes per Proxy weiter, und das Anfordern einer weiteren Variante verändert das Original nicht.

Vom Beispiel zu Ihrer Anwendung

Die Demo verwendet Ihre lokalen CLI-Zugangsdaten und erstellt temporäre signierte Zugriffs-URLs. Sie veröffentlicht kein Verzeichnis, aber ein Upload in ein bereits öffentliches Verzeichnis macht dieses nicht privat. Halten Sie gallery.html privat: Wer die darin enthaltenen URLs hat, kann bis zu deren Ablauf auf diese Derivate zugreifen. Das Beispiel rundet den Ablaufzeitpunkt auf eine volle Stunde, was ein bis zwei Stunden Zugriff und eine bessere Wiederverwendung der URLs ermöglicht. Erzeugen Sie die Seite neu, wenn die URLs ablaufen. Die tatsächliche Cache-Dauer ergibt sich aus dem Header Cache-Control der Antwort; ein Ablauf kann Bytes, die jemand bereits heruntergeladen hat, nicht zurückholen.

Verwenden Sie für eine bereitgestellte Anwendung separate Upload-Zugangsdaten und einen ausschließlich serverseitigen Auslieferungsschlüssel mit smart_cdn:sign. Ein Logout der CLI-Browseranmeldung widerruft den Anmeldeschlüssel, stellen Sie ihn daher nicht als Anwendungsschlüssel bereit. Authentifizieren Sie Benutzer und prüfen Sie vor dem Signieren, ob sie Zugriff auf die gespeicherten Asset-Datensätze haben. Stellen Sie niemals einen Endpunkt bereit, der beliebige vom Browser übermittelte Asset-IDs oder Transformationsparameter signiert.

Wählen Sie die Integration, die zu Ihrer App passt:

• Serverseitige Uploads: Verwenden Sie den Helper storeImage()⁠ aus dem Node SDK und speichern Sie den zurückgegebenen Beleg zusammen mit seinem Eigentümer. Auch bestehende S3- und Assembly-Uploads können kanonische Storage-Datensätze zurückgeben; konstruieren Sie keine Asset-IDs aus Dateinamen.
• React oder Next.js: Nutzen Sie die Bild- und Viewer-Integration⁠ für responsives Rendering, Ladezustände und Galerien. Viewer ist als Alpha-Version veröffentlicht; legen Sie die Version fest, die Sie testen. Bestehende Next.js-Projekte können image init verwenden, ohne eine weitere App anzulegen.
• Galerien mit Uploads von Nutzern: Die Convex-Hochzeitsdemo⁠ kombiniert Uppy-Uploads, reaktive Abfragen von Belegen und autorisierte Foto-/Videoauslieferung. Sie baut auf denselben Storage-Identitäten und Auslieferungs-Helpern auf. Die Zugriffsregeln für Gäste liegen dabei in der Verantwortung der Anwendung.

Was passiert, wenn Sie eine Datei ersetzen?

Das Paar aus Asset und Version wählt exakt die aufbewahrten Bytes aus, nicht „was heute unter diesem Pfad liegt“. Ein Verschieben im Storage erhält diese Identität. Ein Überschreiben erzeugt eine neue Version: Speichern Sie deren neuen Beleg, um die neue Datei anzuzeigen. Alte, an eine Version gebundene URLs verweisen weiterhin auf die alte Version, solange diese aufbewahrt wird und zugänglich ist. Hier ist v die echte Storage-Versions-ID und kein Cachebuster per v=2.

Dasselbe Built-in kann eine Vorschau eines gespeicherten PDFs oder Videos anzeigen, und zwar anhand des eigenen Asset-/Versionsdatensatzes dieser Datei. Der Befehl storage store des Beispiels ist für Bilder gedacht; verwenden Sie für andere Medien einen Assembly- oder S3-Upload und rufen Sie deren kanonische Datensätze ab. Für spezialisierte Verarbeitung verwenden Sie ein eigenes Template mit Signaturpflicht und URL Transform. Prüfen Sie dabei für jeden Robot, ob er das Smart CDN unterstützt. Aufwendigere Videoverarbeitung gehört in eine Assembly, deren Ergebnisse Sie für die Auslieferung speichern.

Beginnen Sie mit dem lauffähigen Beispiel⁠, ändern Sie eine Variante und behalten Sie Ihr Original.