Eigener URL-Shortener mit Workers + KV: vom Einstieg bis zur Praxis

Warum ich einen eigenen URL-Shortener baue

Fast zwei Jahre nutzte ich einen Drittanbieter – eines Morgens waren alle Kurzlinks tot: Der Anbieter kündigte die Schließung an, Hunderte geteilte Links lieferten 404.

Da war klar: Ein Service, der mir gehört. Volle Datenkontrolle, freie Anpassung, kein Risiko durch plötzlich verschwindende Anbieter.

Cloudflare Workers + KV passt perfekt:

• Sehr großzügiges Free-Tier (100.000 Anfragen/Tag)
• Über 200 Edge-Knoten weltweit – sehr schnell
• Einfaches Deployment mit wenigen Zeilen Code
• Daten bleiben unter Ihrer Kontrolle, so lange Sie wollen

Dieser Artikel zeigt, wie ich meinen URL-Shortener mit Workers + KV aufgebaut habe – inklusive benutzerdefinierter Kurzcodes und Zugriffsstatistik. Den Code stelle ich vollständig bereit; in etwa 30 Minuten sind Sie online.

Warum Workers + KV?

Was sind Cloudflare Workers?

Kurz gesagt: Workers sind Serverless-Funktionen im Edge-Netzwerk von Cloudflare. Sie schreiben Code, Cloudflare deployt ihn auf über 200 Knoten weltweit – Anfragen laufen am nächsten Knoten, Latenz bleibt minimal.

Besonders attraktiv: das großzügige Free-Tier:

• 100.000 Anfragen pro Tag
• 10 ms CPU-Zeit pro Anfrage
• Für Privatnutzung und kleine Teams meist ausreichend

Vorteile von KV-Speicher

KV (Key-Value) ist die verteilte Key-Value-Datenbank von Cloudflare, für Edge-Computing optimiert:

• Sehr schnelle Reads: Median 12 ms – Daten liegen im Edge-Cache
• Globale Synchronisation: Nach Schreiben innerhalb von 60 Sekunden weltweit verfügbar
• Free-Tier: 100.000 Reads und 1.000 Writes pro Tag

Für URL-Shortener ideal:

• Kurzcode als Key, Original-URL als Value
• Read-heavy (wenig Erstellen, viele Aufrufe)
• Global verteilt – überall schnell

Vergleich mit Drittanbieter-Shortenern

URL-Shortener von null auf bauen

Genug Theorie – zur Praxis.

Vorbereitung

1. Cloudflare-Konto registrieren

Auf cloudflare.com ein kostenloses Konto anlegen – das reicht aus.

2. Wrangler CLI installieren

Wrangler ist das offizielle CLI-Tool von Cloudflare für Workers-Projekte.

npm install -g wrangler
# oder mit yarn
yarn global add wrangler

Danach anmelden:

wrangler login

Der Browser öffnet sich zur Autorisierung – einfach zulassen.

3. Projekt erstellen

mkdir my-shortlink
cd my-shortlink
wrangler init

Den Anweisungen folgen und ein JavaScript-Projekt wählen (TypeScript geht ebenfalls).

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Schritt 1: KV-Namespace anlegen

KV benötigt einen Namespace – vergleichbar mit einer Tabelle in einer Datenbank.

# KV-Namespace für Produktion
wrangler kv namespace create SHORTLINKS
# KV-Namespace für Preview (lokale Tests)
wrangler kv namespace create SHORTLINKS --preview

Die Ausgabe liefert zwei IDs, etwa:

{ binding = "SHORTLINKS", id = "abc123..." }
{ binding = "SHORTLINKS", preview_id = "def456..." }

Wichtig: Beide IDs notieren – Sie werden gleich benötigt.

Dann wrangler.toml bearbeiten und die KV-Bindung ergänzen:

name = "my-shortlink"
main = "src/index.js"
compatibility_date = "2025-12-01"
# KV-Namespace-Bindung
kv_namespaces = [
  { binding = "SHORTLINKS", id = "Ihre Production-ID", preview_id = "Ihre Preview-ID" }
]

binding = "SHORTLINKS" bedeutet: Im Code greifen Sie über env.SHORTLINKS auf KV zu.

Schritt 2: Basis-Funktionen implementieren

Kernlogik in src/index.js:

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const path = url.pathname.slice(1); // führenden / entfernen
    // Root-Pfad
    if (path === '') {
      return new Response('Willkommen beim URL-Shortener!', { status: 200 });
    }
    // GET: Weiterleitung
    if (request.method === 'GET') {
      const targetUrl = await env.SHORTLINKS.get(path);
      if (targetUrl) {
        return Response.redirect(targetUrl, 301);
      } else {
        return new Response('Kurzlink nicht gefunden', { status: 404 });
      }
    }
    // POST: Kurzlink erstellen
    if (request.method === 'POST') {
      try {
        const body = await request.json();
        const { url: targetUrl, code } = body;
        if (!targetUrl) {
          return new Response('Parameter url fehlt', { status: 400 });
        }
        const shortCode = code || generateRandomCode();
        const existing = await env.SHORTLINKS.get(shortCode);
        if (existing) {
          return new Response('Kurzcode existiert bereits', { status: 409 });
        }
        await env.SHORTLINKS.put(shortCode, targetUrl);
        return new Response(JSON.stringify({
          shortCode,
          shortUrl: `${url.origin}/${shortCode}`,
          targetUrl
        }), {
          status: 201,
          headers: { 'Content-Type': 'application/json' }
        });
      } catch (error) {
        return new Response('Ungültiges Anfrageformat', { status: 400 });
      }
    }
    return new Response('Methode nicht erlaubt', { status: 405 });
  }
};
// Zufälligen Kurzcode erzeugen (6 Zeichen alphanumerisch)
function generateRandomCode(length = 6) {
  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  let code = '';
  for (let i = 0; i < length; i++) {
    code += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return code;
}

Code-Erklärung:

1. GET: Besucher ruft yourdomain.com/abc123 auf – Worker liest abc123 aus KV und leitet mit 301 weiter
2. POST: Empfängt url und optional code – ohne code wird einer zufällig erzeugt und in KV gespeichert
3. generateRandomCode: Erzeugt 6-stellige alphanumerische Codes

Schritt 3: Lokal testen

wrangler dev

Startet einen lokalen Server, meist http://localhost:8787.

Kurzlink erstellen:

curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Antwort:

{
  "shortCode": "aBc123",
  "shortUrl": "http://localhost:8787/aBc123",
  "targetUrl": "https://example.com"
}

Kurzlink aufrufen:

Im Browser http://localhost:8787/aBc123 öffnen – Weiterleitung zu https://example.com.

Wenn alles funktioniert, steht die Basis.

Schritt 4: Benutzerdefinierte Kurzcodes

Der Code unterstützt das bereits – im POST einfach code mitsenden:

curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "code": "my-link"}'

Für mehr Robustheit Validierung ergänzen:

// Vor der Code-Erzeugung im POST-Handler
if (code) {
  if (!/^[a-zA-Z0-9-]+$/.test(code)) {
    return new Response('Ungültiges Kurzcode-Format (nur Buchstaben, Ziffern, Bindestrich)', { status: 400 });
  }
  if (code.length < 3 || code.length > 20) {
    return new Response('Kurzcode muss 3–20 Zeichen lang sein', { status: 400 });
  }
}

So verhindern Sie ungültige oder zu lange Kurzcodes.

Schritt 5: Zugriffsstatistik

Oft reicht Weiterleitung nicht – Sie wollen wissen, wie oft ein Link aufgerufen wurde.

Ansatz:

• Bei jedem Aufruf Zähler um 1 erhöhen
• Statistik in KV unter Key stats:{shortCode} speichern

GET-Handler anpassen:

// GET: Weiterleitung
if (request.method === 'GET') {
  const targetUrl = await env.SHORTLINKS.get(path);
  if (targetUrl) {
    const statsKey = `stats:${path}`;
    // Statistik asynchron aktualisieren – blockiert Weiterleitung nicht
    env.SHORTLINKS.get(statsKey).then(count => {
      const newCount = (parseInt(count) || 0) + 1;
      env.SHORTLINKS.put(statsKey, newCount.toString());
    });
    return Response.redirect(targetUrl, 301);
  } else {
    return new Response('Kurzlink nicht gefunden', { status: 404 });
  }
}

Statistik-Abfrage:

// Vor der GET-Weiterleitung
if (path.startsWith('stats/')) {
  const shortCode = path.slice(6); // stats/ entfernen
  const statsKey = `stats:${shortCode}`;
  const count = await env.SHORTLINKS.get(statsKey);
  return new Response(JSON.stringify({
    shortCode,
    visits: parseInt(count) || 0
  }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Aufruf: http://localhost:8787/stats/abc123 liefert die Anzahl der Zugriffe.

Hinweis: KV unterstützt keine atomaren Operationen – bei hoher Parallelität kann die Statistik ungenau sein. Für präzise Zählung eignen sich Durable Objects; für die meisten privaten Szenarien reicht dieser Ansatz.

Schritt 6: In Produktion deployen

Nach erfolgreichem lokalem Test:

wrangler deploy

Wrangler liefert eine URL wie https://my-shortlink.your-subdomain.workers.dev – Ihr global erreichbarer URL-Shortener.

Eigene Domain binden (optional):

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Mit eigener Domain (z. B. short.example.com) im Cloudflare Dashboard:

1. Workers & Pages öffnen
2. Worker auswählen
3. Settings > Triggers
4. Custom Domain hinzufügen

Danach z. B. https://short.example.com/abc123.

Erweiterte Funktionen

Die Basis steht – optional können Sie folgendes ergänzen:

1. Batch-Erstellung

Mehrere Kurzlinks auf einmal:

// Im POST-Handler für /batch
if (request.method === 'POST' && url.pathname === '/batch') {
  try {
    const body = await request.json();
    const links = body.links; // Format: [{url, code?}, ...]
    if (!Array.isArray(links)) {
      return new Response('links muss ein Array sein', { status: 400 });
    }
    const results = [];
    for (const link of links) {
      const { url: targetUrl, code } = link;
      const shortCode = code || generateRandomCode();
      const existing = await env.SHORTLINKS.get(shortCode);
      if (!existing) {
        await env.SHORTLINKS.put(shortCode, targetUrl);
        results.push({ shortCode, targetUrl, success: true });
      } else {
        results.push({ shortCode, targetUrl, success: false, error: 'Kurzcode existiert bereits' });
      }
    }
    return new Response(JSON.stringify({ results }), {
      headers: { 'Content-Type': 'application/json' }
    });
  } catch (error) {
    return new Response('Ungültiges Anfrageformat', { status: 400 });
  }
}

Aufruf:

curl -X POST http://localhost:8787/batch \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {"url": "https://example1.com", "code": "link1"},
      {"url": "https://example2.com"}
    ]
  }'

2. Ablaufzeit setzen

KV unterstützt TTL (Time To Live) – Kurzlinks laufen automatisch ab:

await env.SHORTLINKS.put(shortCode, targetUrl, {
  expirationTtl: 86400 // nach 24 Stunden löschen, Einheit: Sekunden
});

Benutzerdefinierte Ablaufzeit:

const { url: targetUrl, code, ttl } = body;
const options = {};
if (ttl) {
  options.expirationTtl = parseInt(ttl);
}
await env.SHORTLINKS.put(shortCode, targetUrl, options);

3. Zugriffskontrolle

Nicht jeder soll Kurzlinks erstellen dürfen – einfache API-Token-Prüfung:

// In wrangler.toml Umgebungsvariable
# [vars]
# API_TOKEN = "your-secret-token"
// Vor der POST-Logik
if (request.method === 'POST') {
  const token = request.headers.get('Authorization');
  if (token !== `Bearer ${env.API_TOKEN}`) {
    return new Response('Nicht autorisiert', { status: 401 });
  }
  // ... Erstellen-Logik
}

Aufruf mit Token:

curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"url": "https://example.com"}'

4. Missbrauch verhindern (Rate Limiting)

Schutz vor massenhafter Kurzlink-Erstellung:

const clientIp = request.headers.get('CF-Connecting-IP');
const rateLimitKey = `ratelimit:${clientIp}`;
const count = await env.SHORTLINKS.get(rateLimitKey);
if (parseInt(count) >= 10) {
  return new Response('Zu viele Anfragen – bitte später erneut versuchen', { status: 429 });
}
const newCount = (parseInt(count) || 0) + 1;
await env.SHORTLINKS.put(rateLimitKey, newCount.toString(), {
  expirationTtl: 3600 // 1 Stunde
});

Begrenzt pro IP maximal 10 Erstellungen pro Stunde.

Performance-Optimierung und Best Practices

Performance-Tipps

1. Cache-Strategie

KV-Reads sind bereits schnell (Median 12 ms) – optional zusätzlicher In-Memory-Cache im Worker:

const cache = new Map();
const targetUrl = cache.get(path) || await env.SHORTLINKS.get(path);
if (targetUrl) {
  cache.set(path, targetUrl);
  return Response.redirect(targetUrl, 301);
}

Worker-Speicher ist nicht persistent – nach Neustart leer.

2. KV-Writes reduzieren

Free-Tier: 1.000 Writes/Tag – häufige Statistik-Updates können das Limit erreichen.

Lösungen:

• Durable Objects für atomare Zählung
• Nur alle N Aufrufe in KV schreiben
• Cloudflare Analytics Engine nutzen

3. CORS konfigurieren

Für Frontend-Aufrufe CORS-Header setzen:

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type',
};
if (request.method === 'OPTIONS') {
  return new Response(null, { headers: corsHeaders });
}
return new Response(body, {
  headers: { ...headers, ...corsHeaders }
});

Kostenkontrolle

Das Workers-Free-Tier ist großzügig – trotzdem im Blick behalten:

Free-Tier:

• 100.000 Anfragen/Tag
• KV: 100.000 Reads, 1.000 Writes/Tag
• 10 ms CPU-Zeit pro Anfrage

Kosten über Free-Tier (Workers Paid ab 5 $/Monat):

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

• 0,50 $ pro Million Anfragen
• KV-Read: 0,50 $ pro Million
• KV-Write: 5,00 $ pro Million
• KV-Speicher: 0,50 $ pro GB/Monat

Für Privatnutzung reicht das Free-Tier; kleine Teams mit einigen zehntausend Aufrufen/Tag ebenfalls.

Anfragen sparen:

• 301 statt 302 (Browser-Cache)
• Statische Admin-Seiten über Workers Pages – keine Worker-Anfragen
• TTL für automatische Bereinigung abgelaufener Links

Sicherheit

1. Missbrauch verhindern

Öffentliche Shortener können für bösartige Links genutzt werden.

Empfehlungen:

• API-Token-Validierung
• Blacklist bekannter Schad-Domains
• Ersteller-IP protokollieren

2. Kurzcode-Kollisionen

62^6 ≈ 56,8 Mrd. Möglichkeiten – trotzdem prüfen:

const existing = await env.SHORTLINKS.get(shortCode);
if (existing) {
  return new Response('Kurzcode existiert bereits', { status: 409 });
}

3. Ziel-URLs einschränken

Whitelist erlaubter Domains:

const allowedDomains = ['example.com', 'mywebsite.com'];
const targetDomain = new URL(targetUrl).hostname;
if (!allowedDomains.some(d => targetDomain.endsWith(d))) {
  return new Response('Ziel-Domain nicht erlaubt', { status: 403 });
}

Meine Praxis-Erfahrung

Seit Monaten im Einsatz – ein ehrlicher Erfahrungsbericht:

Vorteile:

• Sehr schnell: Globale Latenz meist unter 50 ms – deutlich schneller als frühere Drittanbieter
• Stabil: Cloudflare-Netzwerk, kaum Ausfälle
• Wenig Wartung: Auto-Scaling, kein Stress bei Traffic-Spitzen
• Kostenlos: Einige tausend Anfragen/Tag – weit im Free-Tier

Kleine Stolpersteine:

• KV-Schreiblatenz: Eventuelle Konsistenz – globale Sync kann einige Sekunden dauern; für Shortener meist unkritisch
• Ungenaue Statistik: Keine atomaren Operationen in KV – bei hoher Parallelität Abweichungen; für Präzision Durable Objects (höhere Kosten)

Geplante Erweiterungen:

• Einfaches Dashboard mit Workers Pages
• Cloudflare Analytics für detaillierte Zugriffsdaten
• QR-Code-Generierung für Offline-Sharing

Fazit

Mit Cloudflare Workers + KV bauen Sie einen URL-Shortener schnell und günstig. Kernlogik unter 100 Zeilen, Deployment mit einem Befehl – und die Daten bleiben in Ihrer Hand, ohne Risiko durch verschwindende Drittanbieter.

Wenn Sie ähnliche Anforderungen haben: Einfach ausprobieren. Den Code finden Sie oben – in etwa 30 Minuten sind Sie online.

Kernschritte im Überblick:

1. Cloudflare-Konto, Wrangler installieren
2. KV-Namespace anlegen, wrangler.toml konfigurieren
3. GET (Weiterleitung) und POST (Erstellen) implementieren
4. Lokal testen, deployen

Statistik, Batch-Erstellung, Ablaufzeit – alles lässt sich schrittweise ergänzen. Der Code gehört Ihnen – anpassen, wie Sie möchten.

Bei Fragen gerne in den Kommentaren – viel Erfolg beim Aufbau Ihres eigenen URL-Shorteners!