Projektbilder mit jsDelivr und GitHub Pages ausliefern

Tim Koschützki

Mitgründer · Berlin, Deutschland · Bio anzeigen

Für ein kleines öffentliches Projekt können Sie ein Bild von GitHub über eine commitgebundene jsDelivr-URL ausliefern. Diese Anleitung bereitet ein PNG vor, veröffentlicht die erzeugte Datei und ergänzt optional eine Kopie auf GitHub Pages mit einem JavaScript-Fallback. Beide URLs verweisen auf dasselbe Bild.

Zu den Diensten passende Dateien auswählen

jsDelivr ist ein CDN-Dienst, keine JavaScript-Bibliothek zum Installieren. Sein GitHub-Endpunkt ruft Dateien direkt aus dem Repository ab; GitHub Pages ist keine Voraussetzung. Pages und jsDelivr sind alternative Wege zur Auslieferung der Dateien. Keiner der beiden Dienste ändert die Größe des PNGs in diesem Beispiel oder komprimiert es erneut.

Nutzen Sie dieses kostenlose Bild-CDN für Dateien eines öffentlichen Projekts, etwa einen Screenshot in einer Open-Source-Kartendemo. Die Nutzungsrichtlinie⁠ von jsDelivr untersagt allgemeines Datei- oder Medienhosting, einschließlich der Speicherung von Uploads einer Bildhosting-Website. Sie erkennt legitime Projekte wie Apps und Spiele mit Bilddateien ausdrücklich an. Stellen Sie für Ihr Projekt eine öffentliche Dokumentation und eine geeignete Lizenz bereit und veröffentlichen Sie nur Bilder, die Sie verbreiten dürfen.

GitHub Pages ist für öffentliche Repositorys auf GitHub Free verfügbar. Zu den Limits⁠ gehören maximal 1 GB für die veröffentlichte Website und ein weiches Bandbreitenlimit von 100 GB pro Monat. Pages schränkt auch die Nutzung des Dienstes für den Betrieb eines Onlinegeschäfts, einer E-Commerce-Website oder eines kommerziellen SaaS-Angebots ein. Diese Dienste eignen sich kaum für private Uploads oder ein allgemeines Bildhosting-Geschäft.

Ein PNG zur Veröffentlichung vorbereiten

Beginnen Sie in einer lokalen Arbeitskopie Ihres öffentlichen Projekts auf dem Branch main. Das Beispiel-Repository heißt map-demo; ersetzen Sie YOUR-USERNAME und map-demo in URLs durch Ihr Konto und Repository. Diese Anleitung setzt ein Yarn-4-Projekt, Node.js 24 oder neuer, eine POSIX-Shell und keine bestehende Website in docs/ voraus. Der lokale Bild-Workflow wurde mit Node.js 26.8.1 und sharp 0.35.4 unter Linux getestet.

Installieren Sie das Bildverarbeitungswerkzeug sharp⁠ und erstellen Sie die Verzeichnisse für die Eingabe und die Veröffentlichung:

corepack yarn add --dev --exact sharp@0.35.4 &&
  mkdir -p original-images docs/images

Legen Sie einen nicht animierten Screenshot als 8-Bit-sRGB-PNG in original-images/map.png ab. Das folgende HTML geht von 640 × 360 Pixeln aus; passen Sie die HTML-Abmessungen und den Alternativtext an Ihr Bild an.

Speichern Sie dies als optimize.cjs im Stammverzeichnis des Repositorys. Das Skript verarbeitet Dateien mit der Endung .png direkt in original-images/ und schreibt sie mit denselben Dateinamen in ein neues Versionsverzeichnis:

const fs = require('node:fs/promises')
const path = require('node:path')
const sharp = require('sharp')

async function optimizeImage(inputPath, outputPath) {
  const image = sharp(inputPath)
  const metadata = await image.metadata()
  if (metadata.format !== 'png') throw new Error(`Expected a PNG: ${inputPath}`)
  await image.png({ compressionLevel: 9, palette: false }).toFile(outputPath)
}

async function processDirectory(inputDir, outputDir) {
  const files = await fs.readdir(inputDir)
  // A published version must not be overwritten by a later run.
  await fs.mkdir(outputDir)

  for (const file of files) {
    const inputPath = path.join(inputDir, file)
    const stat = await fs.stat(inputPath)
    if (!stat.isFile() || !file.endsWith('.png')) continue
    await optimizeImage(inputPath, path.join(outputDir, file))
  }
}

processDirectory('original-images', 'docs/images/v1').catch((error) => {
  console.error(error)
  process.exitCode = 1
})

Führen Sie es einmal aus:

corepack yarn node optimize.cjs

Öffnen Sie docs/images/v1/map.png und vergleichen Sie es mit dem Original. Das Skript behält die Abmessungen bei und verwendet PNG-Komprimierung ohne Palettenquantisierung. sharp konvertiert normalerweise nach sRGB und entfernt Metadaten. Eine kleinere Datei ist nicht garantiert: Vergleichen Sie die Dateigrößen, bevor Sie die Ausgabe übernehmen. Die PNG-Einstellung quality würde die Palettenquantisierung aktivieren und könnte zu Farbverlusten führen; siehe die Ausgabeoptionen⁠ von sharp.

Ein erneuter Durchlauf schlägt fehl, wenn docs/images/v1 bereits existiert; diese Version bleibt dabei unverändert. Auch eine beschädigte Eingabe führt zum Abbruch mit einem Fehler; dabei kann ein teilweise geschriebenes neues Verzeichnis zurückbleiben. Veröffentlichen Sie dieses Verzeichnis nicht. Entfernen Sie nach dem Korrigieren der Eingabe nur das fehlgeschlagene, unveröffentlichte Ausgabeverzeichnis, bevor Sie es erneut versuchen.

Das erzeugte Bild committen

Prüfen Sie, ob docs/images/v1/map.png das tatsächliche PNG ist und kein Git-LFS-Zeiger. Committen Sie die erzeugte Datei selbst, damit jsDelivr sie abrufen kann. Führen Sie Folgendes im Stammverzeichnis des Repositorys aus, ohne dass andere Änderungen zum Commit vorgemerkt sind:

git add docs/images/v1/map.png &&
  git commit -m "Add versioned map screenshot" &&
  git push origin main &&
  git rev-parse HEAD

Bewahren Sie den vollständigen Commit-Hash auf, den der letzte Befehl ausgibt. Im Folgenden steht COMMIT-SHA für diesen Hash des Commits, der das PNG enthält. Bewahren Sie auch optimize.cjs, package.json und yarn.lock zusammen mit dem Quellcode Ihres Projekts auf; node_modules/ gehört nicht in den Commit.

Die commitgebundene jsDelivr-URL verwenden

Ihre Bild-URL lautet:

https://cdn.jsdelivr.net/gh/YOUR-USERNAME/map-demo@COMMIT-SHA/docs/images/v1/map.png

Öffnen Sie sie in einem Browser, nachdem Sie die Platzhalter ersetzt haben. Sie sollte das erzeugte PNG anzeigen. Dafür ist weder ein jsDelivr-Konto noch ein Pages-Deployment erforderlich. Dies ist das dokumentierte GitHub-URL-Format⁠.

Verwenden Sie einen vollständigen Commit-Hash statt main, latest oder einer URL ohne Versionsangabe. jsDelivr speichert statische Versionen und Commit-URLs dauerhaft im Cache⁠ und versieht sie mit langlebigen Cache-Headern. Veröffentlichen Sie geänderte Bilder in einem neuen Commit und aktualisieren Sie die URL; das Löschen des Originals auf GitHub entfernt eine Kopie im Cache nicht zuverlässig.

GitHub Pages als optionalen Fallback ergänzen

Sie können die jsDelivr-URL sofort auf Ihrer eigenen Website verwenden. Um diesem Beispiel einen zweiten Auslieferungsweg zu geben, veröffentlichen Sie docs/ über Pages. Speichern Sie diese Seite als docs/index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Map demo</title>
    <script src="image.js" defer></script>
  </head>
  <body>
    <h1>Map demo</h1>
    <img id="my-image" alt="Screenshot of the map demo" width="640" height="360" />
    <noscript>Enable JavaScript to load this image demo.</noscript>
  </body>
</html>

Zuverlässigkeit und Fallback

Speichern Sie Folgendes als docs/image.js. Ersetzen Sie YOUR-USERNAME und COMMIT-SHA sowie map-demo, falls Ihr Repository anders heißt. Verwenden Sie den Commit-Hash des Bildes aus dem vorherigen Schritt; die Seite und das Skript können Sie später committen.

function loadImage(imageElement, primarySrc, fallbackSrc) {
  imageElement.onerror = function () {
    imageElement.onerror = null
    console.warn('Primary CDN failed, using fallback')
    imageElement.src = fallbackSrc
  }
  imageElement.src = primarySrc
}

const img = document.getElementById('my-image')
if (!(img instanceof HTMLImageElement)) throw new Error('Missing image element: my-image')
loadImage(
  img,
  'https://cdn.jsdelivr.net/gh/YOUR-USERNAME/map-demo@COMMIT-SHA/docs/images/v1/map.png',
  'https://YOUR-USERNAME.github.io/map-demo/images/v1/map.png',
)

Der Handler wechselt bei einem Bildfehler einmalig zu Pages. Falls beide Ursprünge ausfallen, bleibt der Alternativtext des Bildes verfügbar und es erfolgen keine weiteren Versuche. Für eine Anfrage, die weiterhin wartet, gibt es kein Zeitlimit, und beide Wege nutzen weiterhin GitHub als gemeinsame Quelle. Dies ist ein begrenzter Fallback, keine Verfügbarkeitsgarantie.

Erstellen Sie eine leere Datei namens docs/.nojekyll, um die Jekyll-Verarbeitung zu deaktivieren⁠, und veröffentlichen Sie dann die Seite und das Skript:

touch docs/.nojekyll &&
  git add docs/.nojekyll docs/index.html docs/image.js &&
  git commit -m "Add image demo page" &&
  git push origin main

Öffnen Sie im Repository unter Settings den Bereich Pages. Unter Build and deployment setzen Sie Source auf Deploy from a branch, wählen main und /docs und klicken dann auf Save. Die Veröffentlichungsanleitung⁠ von GitHub beschreibt diese Bedienelemente und den Deployment-Lauf, den Sie bei einer fehlgeschlagenen Veröffentlichung prüfen sollten. Die Veröffentlichung aus einem Branch nutzt einen von GitHub verwalteten Actions-Workflow; ein eigener Optimierungs-Workflow ist nicht erforderlich.

Warten Sie auf ein erfolgreiches Deployment, bevor Sie https://YOUR-USERNAME.github.io/map-demo/ öffnen. Dies setzt die Standarddomain der Projektwebsite ohne eigene Domain voraus. Die Pfade unterscheiden sich, weil Pages den Inhalt von docs/ veröffentlicht, während jsDelivr aus dem Stammverzeichnis des Repositorys liest:

Ändern Sie für ein Update das Ausgabeverzeichnis des Optimierers in docs/images/v2, erzeugen und prüfen Sie das neue Bild und committen Sie es. Verwenden Sie den neuen Commit-Hash und den Pfad v2 in der CDN-URL des Skripts und v2 in seiner Pages-URL. Stellen Sie die neue Datei bereit, bevor Sie die Nutzer der URLs umstellen. Behalten Sie v1 für alte Links bei. Pages bindet eine URL nicht an einen Git-Commit: Das Versionsverzeichnis bleibt nur stabil, wenn Sie seinen Inhalt unverändert lassen.

Ihre Einrichtung testen

Öffnen Sie zunächst beide Bild-URLs direkt. Ein 404-Fehler bedeutet meist, dass die Datei in der festgelegten Revision nicht committet wurde, der Pfad oder die Groß- und Kleinschreibung abweicht oder Pages den ausgewählten Ordner noch nicht bereitgestellt hat. Prüfen Sie, ob jede Antwort ein PNG und keine HTML-Fehlerseite ist.

Prüfen Sie auf der Demoseite mit der Netzwerkanalyse Ihres Browsers die Bildanfrage und die Abmessungen des Bildes. Blockieren Sie die genaue jsDelivr-Bild-URL und laden Sie die Seite neu: Die Pages-Anfrage sollte erfolgreich sein. Blockieren Sie dann beide URLs und laden Sie erneut: Für jede URL sollte es einen Versuch geben, wobei der Alternativtext des Bildes weiterhin vorhanden ist. Heben Sie die Blockierung anschließend auf. Testen Sie das Ladeverhalten des Bildes, nicht nur eine erfolgreiche Seitenantwort.

Sicherheit

CORS-Header

Ein gewöhnliches Element <img> mit einer ursprungsübergreifenden Quelle kann ohne Aktivierung von CORS angezeigt werden. Für das Auslesen seiner Pixel mit Canvas gelten zusätzliche CORS-Anforderungen⁠. Diese Demo zeigt das Bild nur an. CORS ist keine Authentifizierung und schränkt nicht ein, wer eine öffentliche Datei herunterladen kann.

Hotlinking verhindern

JavaScript auf Ihrer Seite kann andere nicht daran hindern, die öffentliche Bild-URL einzubetten. Nutzen Sie diesen Workflow nicht für private Bilder. Verwenden Sie zur Zugriffskontrolle einen Speicher und einen Auslieferungsdienst, die Autorisierung oder signierte URLs durchsetzen können.

Wenn Sie mehr als eine Bildgröße benötigen

Dieses Beispiel veröffentlicht ein PNG mit seinen ursprünglichen Abmessungen. Das Hinzufügen von srcset oder eines Elements <picture> erzeugt keine kleineren Bilder oder AVIF/WebP-Dateien: Diese Dateien müssen zuerst erzeugt und committet werden. Ein responsiver Fallback muss außerdem fehlgeschlagene Kandidaten in srcset und <source> entfernen, bevor er src ändert. Daher ist der einfache Handler oben bewusst für ein einzelnes <img> ohne diese Kandidaten ausgelegt. Für dynamische Größen oder Formate bietet sich ein Dienst zur Bildtransformation an, etwa die API zur Bildverarbeitung von Transloadit.