new WebSocket() — Methode · JavaScript-Referenz

Signatur

new WebSocket(url, protocols)

Beschreibung

Der Konstruktor WebSocket() erzeugt eine Verbindung, über die Client und Server dauerhaft und in beide Richtungen Nachrichten austauschen können. Man nutzt das für Chats, Live-Dashboards, Mehrspieler-Spiele oder Benachrichtigungen, also überall dort, wo ständiges HTTP-Polling zu träge oder zu teuer wäre.

Der Verbindungsaufbau beginnt sofort beim Aufruf und läuft asynchron. Das zurückgegebene Objekt hat zunächst readyState === WebSocket.CONNECTING (0). Erst nach dem Ereignis open dürfen Sie mit send() Daten senden. Eingehende Nachrichten kommen über das Ereignis message, Fehler über error und das Verbindungsende über close.

Über den optionalen Parameter protocols geben Sie ein oder mehrere Unterprotokolle an (z. B. "graphql-ws"). Der Server wählt eines davon aus. Welches er gewählt hat, steht nach dem Verbindungsaufbau in socket.protocol.

Moderne Browser akzeptieren neben ws: und wss: auch http:/https: und relative URLs. Diese werden automatisch in das passende WebSocket-Schema umgewandelt.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Ziel-URL des WebSocket-Servers. Erlaubt sind `ws:` und `wss:`, in aktuellen Browsern auch `http:`, `https:` und relative URLs. Die URL darf keinen Fragment-Anteil (`#…`) enthalten.
$protocols	string \| string[]	[]	Ein einzelnes Unterprotokoll oder ein Array davon. Jeder Eintrag darf nur einmal vorkommen und muss ein gültiger Token nach RFC 6455 sein. Der Server wählt eines davon aus.

Rückgabewert

Typ

WebSocket

Beschreibung

Ein neues WebSocket-Objekt, dessen Verbindung gerade aufgebaut wird (readyState 0).

Beispiele

Einfache Verbindung mit Ereignis-Handlern

const socket = new WebSocket('wss://echo.websocket.org');

socket.addEventListener('open', () => {
  console.log('Verbunden');
  socket.send('Hallo Server!');
});

socket.addEventListener('message', (event) => {
  console.log('Empfangen:', event.data);
});

socket.addEventListener('close', (event) => {
  console.log(`Geschlossen: Code ${event.code}, sauber: ${event.wasClean}`);
});

socket.addEventListener('error', () => {
  console.error('WebSocket-Fehler');
});

Verbunden Empfangen: Hallo Server!

JSON-Nachrichten mit Unterprotokoll

const socket = new WebSocket('wss://api.example.com/live', ['json.v2', 'json.v1']);

socket.onopen = () => {
  console.log('Gewähltes Protokoll:', socket.protocol);
  socket.send(JSON.stringify({ type: 'subscribe', channel: 'kurse' }));
};

socket.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.type === 'kurs') {
    console.log(`${msg.symbol}: ${msg.preis} €`);
  }
};

Gewähltes Protokoll: json.v2 DAX: 18250.5 €

Promise-basierter Verbindungsaufbau mit Timeout

const connect = (url, timeoutMs = 5000) =>
  new Promise((resolve, reject) => {
    const socket = new WebSocket(url);
    const timer = setTimeout(() => {
      socket.close();
      reject(new Error('Verbindungs-Timeout'));
    }, timeoutMs);

    socket.addEventListener('open', () => {
      clearTimeout(timer);
      resolve(socket);
    }, { once: true });

    socket.addEventListener('error', () => {
      clearTimeout(timer);
      reject(new Error('Verbindung fehlgeschlagen'));
    }, { once: true });
  });

const main = async () => {
  try {
    const socket = await connect('wss://echo.websocket.org');
    socket.send('ping');
  } catch (err) {
    console.error(err.message);
  }
};
main();

Automatischer Neuaufbau mit exponentiellem Backoff

const createReconnectingSocket = (url, onMessage) => {
  let attempt = 0;

  const open = () => {
    const socket = new WebSocket(url);
    socket.onopen = () => { attempt = 0; console.log('Verbunden'); };
    socket.onmessage = (e) => onMessage(e.data);
    socket.onclose = (e) => {
      if (e.code === 1000) return; // absichtlich geschlossen
      const delay = Math.min(30000, 1000 * 2 ** attempt++);
      console.log(`Neuer Versuch in ${delay} ms`);
      setTimeout(open, delay);
    };
  };

  open();
};

createReconnectingSocket('wss://example.com/feed', (data) => console.log(data));

Verbunden

// Wichtig · Fallstricke

SyntaxError: Der Konstruktor wirft einen SyntaxError-DOMException, wenn die URL ungültig ist, ein nicht erlaubtes Schema oder ein Fragment enthält oder wenn protocols doppelte bzw. ungültige Einträge hat. Deshalb bei Nutzereingaben in try…catch einschließen.
Kein Senden vor open: Rufen Sie send() auf, solange noch CONNECTING gilt, wirft das einen InvalidStateError.
Fehler geben kaum Auskunft: Das Ereignis error enthält aus Sicherheitsgründen keine Details. Den Grund erfahren Sie höchstens über code und reason im anschließenden close-Ereignis. Wird keine Verbindung aufgebaut, lautet der Code oft 1006.
Mixed Content: Eine Seite, die über HTTPS läuft, darf kein unverschlüsseltes ws: öffnen. In der Praxis immer wss: verwenden.
Sicherheit: WebSockets unterliegen nicht der Same-Origin-Policy oder CORS. Der Server muss den Origin-Header selbst prüfen, sonst droht Cross-Site WebSocket Hijacking. Eigene HTTP-Header (z. B. Authorization) lassen sich im Browser nicht setzen. Tokens werden daher über Cookies, Query-Parameter (Achtung: landen in Logs) oder eine erste Nachricht übertragen. Eingehende Daten nie ungeprüft per innerHTML einfügen (XSS). Die CSP-Direktive connect-src begrenzt, welche Ziele erlaubt sind.
Kein Backpressure: Wie viele Daten noch nicht gesendet wurden, zeigt bufferedAmount. Für Datenströme mit Backpressure gibt es das experimentelle WebSocketStream (bisher nur Chromium).
Kompatibilität: Wird von allen modernen Browsern unterstützt. http(s):- und relative URLs gehen erst seit etwa 2023. In Node.js ist WebSocket ab Version 22 global verfügbar, davor braucht man z. B. das Paket ws.

Siehe auch

WebSocket WebSocket.prototype.send() WebSocket.prototype.close() WebSocket.readyState new Worker()