Crypto.randomUUID() — Methode · JavaScript-Referenz

Signatur

Crypto.prototype.randomUUID()

Beschreibung

crypto.randomUUID() gibt eine nach RFC 4122 (heute RFC 9562) aufgebaute UUID der Version 4 zurück, zum Beispiel "3b241101-e2bb-4255-8caf-4136c566a962". Von den 128 Bit sind 122 Bit zufällig. Die übrigen 6 Bit legen Version (4) und Variante (8, 9, a oder b) fest.

Die Methode ist die einfachste und sicherste Art, im Browser oder in Node.js eindeutige Kennungen zu erzeugen. Typische Anwendungen sind IDs für neue Datensätze auf dem Client (etwa bei Offline-first-Apps oder optimistischen UI-Updates), Korrelations-IDs für Anfragen und Logs, Schlüssel für Einträge in IndexedDB sowie Dateinamen für Uploads. Eine externe Bibliothek wie uuid braucht man dafür nicht mehr.

Die Zufallswerte kommen aus derselben kryptografisch sicheren Quelle wie bei crypto.getRandomValues(). Im Gegensatz zu selbst gebauten Lösungen mit Math.random() sind die Werte deshalb nicht vorhersagbar. Die Buchstaben in der Ausgabe sind immer klein geschrieben.

Rückgabewert

Typ

string

Beschreibung

Eine 36 Zeichen lange UUID der Version 4 in kleingeschriebener Hexadezimalform im Format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx. Dabei steht y für 8, 9, a oder b.

Beispiele

Einfache UUID erzeugen

const id = crypto.randomUUID();
console.log(id);
console.log(id.length);

"1f0c2a7e-9b3d-4c6a-8e21-5d4f7a9b0c13" (Beispielwert, bei jedem Aufruf anders) 36

Client-seitige ID für einen optimistisch angelegten Eintrag

const todos = [];

const addTodo = async (text) => {
  const todo = { id: crypto.randomUUID(), text, done: false };
  todos.push(todo); // sofort in der Oberfläche anzeigen

  try {
    await fetch('/api/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(todo)
    });
  } catch (err) {
    // Rollback anhand der eindeutigen ID
    const index = todos.findIndex((t) => t.id === todo.id);
    if (index !== -1) todos.splice(index, 1);
    console.error('Speichern fehlgeschlagen:', err);
  }
};

addTodo('Milch kaufen');

Korrelations-ID für Anfragen und Logs

const tracedFetch = async (url, options = {}) => {
  const requestId = crypto.randomUUID();
  console.log(`[${requestId}] → ${url}`);

  const response = await fetch(url, {
    ...options,
    headers: { ...options.headers, 'X-Request-ID': requestId }
  });

  console.log(`[${requestId}] ← ${response.status}`);
  return response;
};

await tracedFetch('/api/status');

[5e8c...-...] → /api/status [5e8c...-...] ← 200

Mit Fallback und Format-Prüfung

const uuidV4 = () => {
  if (typeof crypto?.randomUUID === 'function') {
    return crypto.randomUUID();
  }
  // Fallback über getRandomValues (steht auch ohne Secure Context zur Verfügung)
  const b = crypto.getRandomValues(new Uint8Array(16));
  b[6] = (b[6] & 0x0f) | 0x40; // Version 4
  b[8] = (b[8] & 0x3f) | 0x80; // Variante RFC 4122
  const h = [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
};

const isUuidV4 = (s) =>
  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s);

console.log(isUuidV4(uuidV4()));

true

// Wichtig · Fallstricke

Nur im Secure Context: Im Browser gibt es randomUUID() nur auf Seiten, die über HTTPS oder von localhost geladen werden. Auf einer Seite über einfaches http:// (etwa unter einer LAN-IP-Adresse) ist crypto.randomUUID undefined, und ein Aufruf löst einen TypeError aus. crypto.getRandomValues() funktioniert dagegen auch dort.
Browser-Unterstützung: Die Methode wird unterstützt in Chrome/Edge ab 92, Firefox ab 95 und Safari ab 15.4. Sie funktioniert auch in Web Workern. In Node.js steht sie als crypto.randomUUID() aus node:crypto ab 14.17/15.6 zur Verfügung, über globalThis.crypto ab Node 19. Deno und Bun unterstützen sie ebenfalls.
Nicht als Geheimnis verwenden: Eine UUID ist eine eindeutige Kennung und kein Ersatz für Token, Schlüssel oder Passwörter. Für Sitzungs- oder CSRF-Token besser gezielt Bytes mit getRandomValues() erzeugen, und UUIDs nie für Zugriffskontrolle verwenden (Security by Obscurity).
Nicht sortierbar: v4-UUIDs sind rein zufällig. Als Primärschlüssel in B-Baum-Indizes führen sie zu fragmentierten Einfügungen. Wenn die IDs zeitlich sortierbar sein sollen, sind UUID v7 oder ULID die bessere Wahl. Beide sind jedoch nicht nativ eingebaut.
Kollisionen sind bei 122 Zufallsbits praktisch ausgeschlossen, aber nicht mathematisch unmöglich.
Die Methode muss auf dem crypto-Objekt aufgerufen werden. Wer sie abtrennt (const f = crypto.randomUUID; f()), bekommt einen TypeError (Illegal invocation). Stattdessen crypto.randomUUID.bind(crypto) verwenden.

Siehe auch

Crypto Crypto.getRandomValues() Crypto.subtle SubtleCrypto Window.crypto