WebSocket.close() — Methode · JavaScript-Referenz

Signatur

WebSocket.prototype.close(code, reason)

Beschreibung

Mit close() beendet man eine WebSocket-Verbindung kontrolliert. Der Browser startet dabei den sogenannten Closing Handshake: Er sendet einen Close-Frame an den Server, setzt readyState sofort auf CLOSING (2) und wechselt zu CLOSED (3), sobald der Server geantwortet hat oder die TCP-Verbindung getrennt wurde. Danach wird das close-Event ausgelöst.

Über die optionalen Parameter code und reason kann man der Gegenseite mitteilen, warum die Verbindung beendet wird. Das ist nützlich, wenn der Server zwischen einem gewollten Abmelden, einem Seitenwechsel oder einem Anwendungsfehler unterscheiden soll. Die Werte kommen beim Server im Close-Frame an und stehen auf Clientseite im CloseEvent (event.code, event.reason) zur Verfügung.

Ruft man close() auf, während die Verbindung noch aufgebaut wird (CONNECTING), wird der Versuch abgebrochen; in diesem Fall wird zusätzlich ein error-Event ausgelöst. Ist die Verbindung bereits geschlossen oder im Schließvorgang, hat der Aufruf keine Wirkung.

Parameter

Name	Typ	Default	Beschreibung
$code	number	1005 (kein Status) — bzw. vom Browser gesendet ohne Code	Statuscode für das Schließen. Erlaubt sind nur `1000` (normales Schließen) oder Werte von `3000` bis `4999` (anwendungs- bzw. bibliotheksspezifisch). Andere Werte lösen eine `InvalidAccessError`-`DOMException` aus.
$reason	string	""	Menschenlesbare Begründung. Darf UTF-8-kodiert höchstens 123 Bytes lang sein, sonst wird ein `SyntaxError` ausgelöst.

Beispiele

Verbindung normal schließen

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

socket.addEventListener('open', () => {
  socket.send('Hallo Server');
  // Nach dem Senden sauber schließen
  socket.close(1000, 'Arbeit erledigt');
  console.log('readyState:', socket.readyState);
});

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

readyState: 2 Geschlossen: code=1000, reason=Arbeit erledigt, clean=true

Anwendungsspezifischer Code beim Logout

const LOGOUT_CODE = 4001;
const socket = new WebSocket('wss://example.com/chat');

const logout = () => {
  if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
    socket.close(LOGOUT_CODE, 'Benutzer abgemeldet');
  }
};

document.querySelector('#logout')?.addEventListener('click', logout);

Ungültige Parameter abfangen

const socket = new WebSocket('wss://example.com/live');

try {
  socket.close(1001); // 1001 ist für Clients nicht erlaubt
} catch (err) {
  console.log(err.name);
}

try {
  socket.close(1000, 'x'.repeat(200)); // länger als 123 Bytes
} catch (err) {
  console.log(err.name);
}

InvalidAccessError SyntaxError

Verbindung beim Verlassen der Seite schließen

const socket = new WebSocket('wss://example.com/updates');

window.addEventListener('pagehide', () => {
  socket.close(1000, 'Seite verlassen');
});

// Wichtig · Fallstricke

Erlaubte Codes: Clients dürfen nur 1000 oder 3000–4999 senden. Codes wie 1001 oder 1006 sind reserviert bzw. werden nur vom Browser/Server selbst gesetzt; ein Aufruf damit wirft InvalidAccessError.
Byte-Limit für reason: Die Grenze von 123 Bytes gilt für die UTF-8-Kodierung – Umlaute und Emojis belegen mehrere Bytes.
Asynchron: Nach close() ist die Verbindung noch nicht zu. Bereits gepufferte Daten (bufferedAmount) werden noch gesendet; wer auf das Ende warten will, lauscht auf das close-Event.
Abbruch im Aufbau: Beim Aufruf im Zustand CONNECTING feuern error und close, wasClean ist dann false.
Automatisches Wiederverbinden: Wer eine Reconnect-Logik im close-Handler hat, sollte bei absichtlichem Schließen (z. B. anhand des Codes) nicht erneut verbinden.
Kompatibilität: In allen modernen Browsern verfügbar; in Node.js ist WebSocket ab Version 22 global vorhanden (vorher z. B. über das Paket ws).

Siehe auch

WebSocket WebSocket.send() WebSocket.readyState CloseEvent WebSocket.bufferedAmount ResizeObserver.unobserve()