Eine Bildoptimierungspipeline mit CDN aufbauen
Erstellen Sie einen Worker, der ein eingebettetes öffentliches Bild in drei WebP-Ressourcen umwandelt und das HTML ausliefert, das zwischen ihnen auswählt. Sie können die decodierten Bilder lokal prüfen, dann denselben Code mit explizit aktiviertem Workers Cache bereitstellen und prüfen, ob wiederholte Anfragen tatsächlich aus dem Cache bedient werden.
Bild-CDNs verstehen
Eine Bildpipeline braucht sowohl Transformation als auch Auslieferung. Hier ändert die
Images-Bindung die Bildgröße anhand der rohen Bilddaten
innerhalb eines Workers. Workers Cache kann die resultierende
HTTP-Antwort ausliefern, ohne diesen Worker erneut auszuführen. Er muss explizit aktiviert werden;
ein Cache-Control-Header allein aktiviert ihn nicht.
Dieses Beispiel legt WebP als Ausgabeformat fest und stellt nur drei Bildpfade bereit. Die Quelle ist ein synthetisches PNG mit 1.280 × 640 Pixeln und vier Farbflächen. So bleibt das Beispiel eigenständig und leicht überprüfbar; es demonstriert weder fotografische Qualität noch eine verringerte Dateigröße. Es gibt keine Uploads, privaten Bilder oder beliebigen Quell-URLs.
Das Projekt vorbereiten
Die folgenden Befehle verwenden Bash unter Linux. Getestet wurden
Node.js 26.12.1, Corepack, Yarn 4.12.0 und
Wrangler 4.154.0. Node 26 ist eine gepflegte Versionsreihe; diese Versionsbindungen dienen der
Reproduzierbarkeit und bedeuten nicht, dass andere Patchversionen inkompatibel sind. Corepack ist
unter Node 26 eine separate Voraussetzung: Folgen Sie der
Installationsanleitung, wenn corepack
nicht verfügbar ist. Außerdem benötigen Sie cURL für die Cache-Prüfung nach der Bereitstellung und
einen Browser, der WebP unterstützt.
Für die Bereitstellung benötigen Sie ein Cloudflare-Konto, in dem Workers und die Images-Bindung
verfügbar sind, eine bestehende Subdomain unter workers.dev und eine
Wrangler-Authentifizierung für dieses Konto. Die lokale Entwicklung unten erfordert keine
Bereitstellung in der Cloud. Lesen Sie vor der Bereitstellung Cloudflares
Authentifizierungsoptionen;
Bildtransformationen und Worker-Anfragen können Kosten verursachen.
Fügen Sie diesen Block in einem Verzeichnis mit Schreibzugriff ein. Er verweigert das Ersetzen eines
vorhandenen Verzeichnisses namens image-pipeline und belässt Ihre Shell im
ursprünglichen Verzeichnis:
(
for tool in node corepack; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'Missing prerequisite: %s\n' "$tool" >&2
exit 1
}
done
mkdir image-pipeline &&
cd image-pipeline &&
mkdir src &&
cat > package.json <<'JSON' &&
{
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"scripts": {
"start": "wrangler dev --ip 127.0.0.1 --port 8787",
"build": "wrangler deploy --dry-run --outdir dist",
"deploy": "wrangler deploy"
},
"devDependencies": { "wrangler": "4.154.0" }
}
JSON
printf 'nodeLinker: node-modules\nignorePath: true\nenableScripts: true\nnpmMinimalAgeGate: 0\n' > .yarnrc.yml &&
touch yarn.lock
)
Die lokale Lockdatei grenzt dieses Beispiel als eigenes Yarn-Projekt ab. Die
Yarn-Einstellungen wählen node_modules und
behalten die festgelegte ausführbare Yarn-Datei bei, statt yarnPath aus einem
übergeordneten Projekt zu übernehmen. Sie erlauben außerdem die Installationsskripte der nativen
Abhängigkeiten. Mit npmMinimalAgeGate: 0 installiert dieses isolierte Beispiel die
festgelegte Version ohne die Wartefrist für neue Paketversionen aus einem übergeordneten Projekt;
behalten Sie bei der Integration in eine bestehende Anwendung die Richtlinie Ihrer Organisation bei.
Installieren und prüfen Sie die tatsächliche CLI aus demselben übergeordneten Verzeichnis:
(cd image-pipeline && corepack yarn install && corepack yarn exec wrangler --version)
Erwartet wird 4.154.0. Wenn die Installation fehlschlägt, beheben Sie die
gemeldete Ursache und wiederholen Sie diesen Installationsblock im selben übergeordneten Verzeichnis.
Behalten Sie package.json und das Projektverzeichnis bei; der Erstellungsblock
würde bei erneuter Ausführung das vorhandene Verzeichnis richtigerweise ablehnen. Falls bereits die
Erstellung vorzeitig abgebrochen wurde, prüfen Sie das Verzeichnis, bevor Sie fortfahren, oder wählen
Sie einen neuen, leeren Speicherort.
Die Bildoptimierung einrichten
Speichern Sie dies als image-pipeline/wrangler.jsonc. Wählen Sie für die Bereitstellung einen
Worker-Namen, der Ihnen gehört und den Sie noch nicht verwendet haben, damit das Beispiel keine
bestehende Anwendung ersetzt:
{
"name": "image-pipeline-example",
"main": "src/index.ts",
"workers_dev": true,
"compatibility_date": "2026-10-28",
"images": { "binding": "IMAGES" },
"cache": { "enabled": true, "cross_version_cache": false }
}
Der Eintrag images stellt env.IMAGES bereit.
Der separate Eintrag cache aktiviert
Workers Cache für diesen Worker. Die folgenden Bildantworten
sind öffentlich und für 3.600 Sekunden cachebar; das HTML und die Fehlerantworten verwenden
no-store.
Speichern Sie den vollständigen Worker als image-pipeline/src/index.ts:
interface ImagesBinding {
input(stream: ReadableStream<Uint8Array>): {
transform(options: { width: number }): {
output(options: { format: 'image/webp' }): Promise<{
response(options?: { headers?: Record<string, string> }): Response
}>
}
}
}
const sourceBase64 =
'iVBORw0KGgoAAAANSUhEUgAABQAAAAKAAgMAAAC+nT0yAAAADFBMVEXIPCgoyGQoPMjctCj/cAxvAAADMUlEQVR42u3TQQ0AIAADsQWPmMQkiOAzQk9CsyXlzfJGdBVAgAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAnymVd4uzwJdGCBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAAFECBAgAIIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIECBAAQQIEKAAAgQIUAABAgQogAABAhRAgAABCiBAgAAFECBAgAIIECBAAQQIEKAAAgQIEKAAAgQIUAABAgQogAABAhRAgAA/6QB65UPMTK7o+gAAAABJRU5ErkJggg=='
const source = Uint8Array.from(atob(sourceBase64), (value) => value.charCodeAt(0))
const page = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Responsive image pipeline</title>
<style>body{margin:0}img{display:block;width:100%;max-width:640px;height:auto}</style>
</head>
<body>
<h1>Responsive image pipeline</h1>
<img src="/image/1280.webp"
srcset="/image/320.webp 320w, /image/640.webp 640w, /image/1280.webp 1280w"
sizes="(max-width: 640px) 100vw, 640px" width="1280" height="640"
alt="Four colored panels used to check image resizing">
</body>
</html>`
const widths: Record<string, number> = {
'/image/320.webp': 320,
'/image/640.webp': 640,
'/image/1280.webp': 1280,
}
export default {
async fetch(request: Request, env: { IMAGES: ImagesBinding }): Promise<Response> {
const url = new URL(request.url)
const notFound = () =>
new Response('Not found', { status: 404, headers: { 'Cache-Control': 'no-store' } })
if (request.method !== 'GET' || url.search !== '') return notFound()
if (url.pathname === '/') {
return new Response(page, {
headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
})
}
if (!Object.hasOwn(widths, url.pathname)) return notFound()
const width = widths[url.pathname]
try {
return (
await env.IMAGES.input(new Blob([source]).stream())
.transform({ width })
.output({ format: 'image/webp' })
).response({
headers: {
'Cache-Control': 'public, max-age=3600',
'X-Image-Run': crypto.randomUUID(),
},
})
} catch {
return new Response('Image transformation unavailable', {
status: 503,
headers: { 'Cache-Control': 'no-store' },
})
}
},
}
Nur /image/320.webp, /image/640.webp und
/image/1280.webp wählen eine Transformation aus. Ihre decodierten Abmessungen
sollten jeweils 320 × 160, 640 × 320 und 1.280 × 640 betragen, mit roten und grünen Flächen über
blauen und gelben Flächen. Die Bindung setzt den Inhaltstyp der Antwort anhand des angeforderten
Ausgabeformats. Das Umbenennen von PNG-Daten oder das Setzen eines WebP-Headers würde ein Bild nicht
konvertieren.
Responsive Bilder implementieren
Starten Sie den lokalen Server aus dem übergeordneten Verzeichnis:
(cd image-pipeline && corepack yarn start)
Öffnen Sie http://127.0.0.1:8787/. Sie sollten die vier Flächen sehen, die sich bis zu
einer Anzeigebreite von 640 Pixeln an den Viewport anpassen. Öffnen Sie jeden Bildpfad direkt, um
Inhalt und Abmessungen zu prüfen. Beenden Sie den Server im Vordergrund vor dem nächsten Schritt mit
Ctrl+C. Wenn Port 8787 belegt ist, beenden Sie den anderen Listener oder wählen Sie im Skript
start einen anderen Port, bevor Sie dieses Beispiel starten.
Das Attribut sizes im HTML entspricht diesem CSS-Layout:
100vw bis 640 Pixel, danach 640px.
Die Deskriptoren 320w, 640w und
1280w beschreiben tatsächliche Ressourcenbreiten statt Anzeigebreiten.
Die Attribute width und height reservieren ein
Seitenverhältnis von 2:1, während src das Standardbild bereitstellt.
Siehe die HTML-Regeln zur Bildauswahl.
Prüfen Sie die ausgewählte Bildanfrage im Netzwerkbereich Ihres Browsers. Ein Viewport mit 320 Pixeln bei DPR 1, einer mit 800 Pixeln bei DPR 1 und einer mit 640 Pixeln bei DPR 2 stellen unterschiedliche Anforderungen an die Ressourcen. Verwenden Sie für den Vergleich jeweils neue Browserkontexte: Die Auswahl kann vom Browser, dem Gerätepixelverhältnis und zwischengespeicherten Ressourcen abhängen. Das Markup bietet dem Browser Kandidaten an; es erzwingt keine einheitliche Auswahl in allen Browsern.
Lokal nutzt Wrangler eine eingeschränkte Offline-Implementierung von Images, die die Größenänderung und das explizite Format dieses Beispiels unterstützt. Damit lassen sich die Seite und die Transformationen prüfen, aber kein Cache-Treffer nach der Bereitstellung bei Cloudflare nachweisen. Cloudflare dokumentiert diese Einschränkungen lokaler Bindungen.
Bereitstellen und den Cache beobachten
Erstellen Sie zuerst den Build. Ein erfolgreicher Probelauf schreibt den gebündelten Worker nach
image-pipeline/dist/index.js, ohne ihn hochzuladen. Ein erneuter Build aktualisiert dieses
entbehrliche Ausgabeverzeichnis:
(cd image-pipeline && corepack yarn build)
Nachdem Sie Ihr Konto, die Authentifizierung und den unbenutzten Worker-Namen bestätigt haben, stellen Sie den Worker aus demselben übergeordneten Verzeichnis bereit:
(cd image-pipeline && corepack yarn deploy)
Öffnen Sie die von Wrangler ausgegebene URL workers.dev und prüfen Sie die
Seite und die drei Bild-URLs erneut. Setzen Sie diesen Ursprung in beide folgenden Befehle ein.
Dies sind vollständige GET-Anfragen, die den Antwortkörper verwerfen und die Header ausgeben;
cURL verwendet keinen Bildcache eines Browsers:
(
command -v curl >/dev/null 2>&1 || { printf 'Install cURL first\n' >&2; exit 1; }
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp' &&
curl -fsS -D - -o /dev/null 'https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/image/640.webp'
)
Achten Sie bei einer wiederholten Anfrage auf CF-Cache-Status: HIT und vergleichen Sie
X-Image-Run mit der vorherigen Antwort. Bei einem Treffer sollte die Markierung
erhalten bleiben, die beim Erzeugen dieser Antwort durch den Worker generiert wurde. Ein Header
Cache-Control, identische Bilddaten oder eine unveränderte Markierung allein
beweisen keinen Treffer. Fehlt der Status, prüfen Sie die bereitgestellte Einstellung
cache.enabled; bei wiederholten Cache-Misses müssen die Antwortrichtlinie und
der Cache-Schlüssel geprüft werden. Cloudflares
Anleitung zur Cache-Fehlersuche erklärt diese Statuswerte.
Betrachten Sie eine lokale Vorschau nicht als gleichwertigen Nachweis.
Damit weisen Sie eine Cache-Beobachtung nach, führen aber keinen Geschwindigkeits- oder Bandbreiten-Benchmark durch. Messen Sie die tatsächlichen Bytes und Seitenmetriken anhand repräsentativer Bilder, bevor Sie eine Leistungsverbesserung behaupten.
Das öffentliche Beispiel klar begrenzen
Jedes Bild hier ist öffentlich, und der Worker akzeptiert eine feste Auswahl von Pfaden. Behalten Sie diese Grenze beim Experimentieren bei: Beliebige URLs zu akzeptieren würde eine andere Problemstellung beim Abruf der Quellen und bei der Zugriffskontrolle schaffen. Setzen Sie in diesem öffentlichen, cachebaren Antwortpfad keine vertraulichen Bilder ein. Die private Auslieferung benötigt ein eigenes Konzept für Autorisierung und Caching.
Ersetzen Sie für eine echte Bildbibliothek die synthetische Quelle erst, nachdem Sie festgelegt
haben, wie Originale gespeichert und Zugriffe autorisiert werden. Prüfen Sie dann die decodierten
Ausgabebreiten, bevor Sie sie in srcset angeben. Verwaltete Verarbeitung
und Auslieferung sind eine weitere Option; siehe
Smart CDN von Transloadit.
Möchten Sie das lieber nicht selbst betreiben?
Transloadits Smart CDN transformiert Dateien bei Abruf und liefert sie aus.
