バージョン: 4.x

サーバーオプション

Socket.IOサーバーオプション

以下のオプションは、Socket.IOサーバーの動作に影響します。

`adapter`

デフォルト値: require("socket.io-adapter") (インメモリアダプター、ソースコードはこちら)

CommonJS
ES modules
TypeScript

const { Server } = require("socket.io");
const { createAdapter } = require("@socket.io/redis-adapter");
const { createClient } = require("redis");

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-adapter";
import { createClient } from "redis";

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-adapter";
import { createClient } from "redis";

const pubClient = createClient({ host: "localhost", port: 6379 });
const subClient = pubClient.duplicate();

const io = new Server({
  adapter: createAdapter(pubClient, subClient)
});

io.listen(3000);

`cleanupEmptyChildNamespaces`

v4.6.0で追加

デフォルト値: false

接続されているソケットがない子名前空間を削除するかどうか。

このオプションは、各名前空間が独自のアダプターインスタンスを作成するため、動的な名前空間を多数作成する場合に役立ちます。

このオプションを有効にすると（デフォルトでは無効）、ソケットが動的な名前空間から切断され、他のソケットが接続されていない場合、名前空間がクリーンアップされ、アダプターが閉じられます。

`connectionStateRecovery`

v4.6.0で追加

デフォルト値: undefined

接続状態の回復機能のオプション

const io = new Server(httpServer, {
  connectionStateRecovery: {
    // the backup duration of the sessions and the packets
    maxDisconnectionDuration: 2 * 60 * 1000,
    // whether to skip middlewares upon successful recovery
    skipMiddlewares: true,
  }
});

skipMiddlewares オプションが true に設定されている場合、接続が正常に回復されたときにミドルウェアはスキップされます

function computeUserIdFromHeaders(headers) {
  // to be implemented
}

// this middleware will be skipped if the connection is successfully recovered
io.use(async (socket, next) => {
  socket.data.userId = await computeUserIdFromHeaders(socket.handshake.headers);

  next();
});

io.on("connection", (socket) => {
  // the userId attribute will either come:
  // - from the middleware above (first connection or failed recovery)
  // - from the recevery mechanism
  console.log("userId", socket.data.userId);
});

`connectTimeout`

デフォルト値: 45000

名前空間に正常に参加できなかったクライアントを切断するまでの時間 (ミリ秒)。

`parser`

デフォルト値: socket.io-parser

使用するパーサー。ドキュメントはこちらを参照してください。

`path`

デフォルト値: /socket.io/

サーバー側でキャプチャされるパスの名前です。

注意

サーバーとクライアントの値は一致する必要があります（パス書き換えプロキシを使用している場合を除く）。

サーバー

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
  path: "/my-custom-path/"
});

クライアント

import { io } from "socket.io-client";

const socket = io("https://example.com", {
  path: "/my-custom-path/"
});

`serveClient`

デフォルト値: true

クライアントファイルを配信するかどうか。 true の場合、異なるバンドルが以下の場所で配信されます

<url>/socket.io/socket.io.js
<url>/socket.io/socket.io.min.js
<url>/socket.io/socket.io.msgpack.min.js

(関連するソースマップを含む)

こちらも参照してください。

低レベルエンジンオプション

以下のオプションは、基盤となるEngine.IOサーバーの動作に影響します。

`addTrailingSlash`

v4.6.0で追加

デフォルト値: true

デフォルトで追加されていた末尾のスラッシュが無効になりました

import { createServer } from "node:http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
addTrailingSlash: false
});

上記の例では、クライアントは末尾のスラッシュを省略し、/socket.io/ の代わりに /socket.io を使用できます。

`allowEIO3`

デフォルト値: false

Socket.IO v2クライアントとの互換性を有効にするかどうか。

参照: 2.xから3.0への移行

例

const io = new Server(httpServer, {
  allowEIO3: true // false by default
});

`allowRequest`

デフォルト: -

指定されたハンドシェイクまたはアップグレードリクエストを最初のパラメーターとして受信し、続行するかどうかを決定できる関数。

例

const io = new Server(httpServer, {
  allowRequest: (req, callback) => {
    const isOriginValid = check(req);
    callback(null, isOriginValid);
  }
});

これは、initial_headersイベントと組み合わせて、クライアントにCookieを送信するためにも使用できます

import { serialize } from "cookie";

const io = new Server(httpServer, {
  allowRequest: async (req, callback) => {
    const session = await fetchSession(req);
    req.session = session;
    callback(null, true);
  }
});

io.engine.on("initial_headers", (headers, req) => {
  if (req.session) {
    headers["set-cookie"] = serialize("sid", req.session.id, { sameSite: "strict" });
  }
});

参照

`allowUpgrades`

デフォルト値: true

トランスポートのアップグレードを許可するかどうか。

`cookie`

デフォルト値: -

cookieモジュールに転送されるオプションのリスト。利用可能なオプション

domain
encode
expires
httpOnly
maxAge
path
sameSite
secure

例

import { Server } from "socket.io";

const io = new Server(httpServer, {
  cookie: {
    name: "my-cookie",
    httpOnly: true,
    sameSite: "strict",
    maxAge: 86400
  }
});

情報

Socket.IO v3以降、デフォルトではCookieが送信されなくなりました (リファレンス)。

`cors`

デフォルト値: -

corsモジュールに転送されるオプションのリスト。詳細はこちらを参照してください。

サンプル

特定のオリジンを許可する

const io = new Server(httpServer, {
  cors: {
    origin: ["https://example.com"]
  }
});

ローカル開発のための特定のオリジンを許可する

const io = new Server(httpServer, {
  cors: {
    origin: process.env.NODE_ENV === "production" ? false : ["https://:3000"]
  }
});

指定されたオリジン、ヘッダー、および資格情報（Cookie、認証ヘッダー、TLSクライアント証明書など）を許可する

const io = new Server(httpServer, {
  cors: {
    origin: ["https://example.com", "https://dev.example.com"],
    allowedHeaders: ["my-custom-header"],
    credentials: true
  }
});

備考

ブラウザでCookie、認証ヘッダー、TLSクライアント証明書などの資格情報を送信する場合は、クライアント側でwithCredentialsオプションをtrueに設定する必要があります

import { io } from "socket.io-client";

const socket = io("https://my-backend.com", {
  withCredentials: true
});

詳細はこちら。

すべてのオリジンを許可する

const io = new Server(httpServer, {
  cors: {
    origin: "*"
  }
});

危険

この場合、どのドメインもサーバーにアクセスできるようになるため、クロスオリジンリソースシェアリング（CORS）によって提供されるセキュリティが無効になります。注意して使用してください。

利用可能なオプション

オプション	説明
`origin`	Access-Control-Allow-Origin CORSヘッダーを設定します。
`methods`	Access-Control-Allow-Methods CORSヘッダーを設定します。カンマ区切りの文字列（例： 'GET,PUT,POST'）または配列（例： `['GET', 'PUT', 'POST']`）を想定しています。
`allowedHeaders`	Access-Control-Allow-Headers CORSヘッダーを設定します。カンマ区切りの文字列（例： 'Content-Type,Authorization'）または配列（例： `['Content-Type', 'Authorization']`）を想定しています。指定されていない場合、デフォルトではリクエストのAccess-Control-Request-Headersヘッダーで指定されたヘッダーを反映します。
`exposedHeaders`	Access-Control-Expose-Headers CORSヘッダーを設定します。カンマ区切りの文字列（例： 'Content-Range,X-Content-Range'）または配列（例： `['Content-Range', 'X-Content-Range']`）を想定しています。指定しない場合、カスタムヘッダーは公開されません。
`credentials`	Access-Control-Allow-Credentials CORSヘッダーを設定します。ヘッダーを渡すには`true`に設定します。それ以外の場合は省略されます。
`maxAge`	Access-Control-Max-Age CORSヘッダーを設定します。ヘッダーを渡すには整数に設定します。それ以外の場合は省略されます。
`preflightContinue`	CORSプリフライトリスポンスを次のハンドラーに渡します。
`optionsSuccessStatus`	一部のレガシーブラウザ（IE11、さまざまなSmartTV）が`204`で詰まるため、成功した`OPTIONS`リクエストに使用するステータスコードを提供します。

originオプションの可能な値

Boolean - req.header('Origin') で定義されているように、リクエストオリジンを反映するには、origin を true に設定します。CORS を無効にするには、false に設定します。
String - origin を特定のオリジンに設定します。たとえば、"http://example.com" に設定すると、「http://example.com"」からのリクエストのみが許可されます。
RegExp - origin を、リクエストオリジンのテストに使用される正規表現パターンに設定します。一致する場合、リクエストオリジンが反映されます。たとえば、パターン /example\.com$/ は、「example.com」で終わるオリジンからのリクエストを反映します。
Array - origin を有効なオリジンの配列に設定します。各オリジンは String または RegExp にすることができます。たとえば、["http://example1.com", /\.example2\.com$/] は、「http://example1.com"」または「example2.com」のサブドメインからのリクエストを受け入れます。
Function - origin を、カスタムロジックを実装する関数に設定します。この関数は、リクエストオリジンを最初のパラメーターとして、コールバック（シグネチャ err [object], allow [bool] を想定）を2番目のパラメーターとして受け取ります。

備考

複数のドメインがあっても、オプションの名前は origin です (origins ではありません)

const io = new Server(httpServer, {
  cors: {
    // BAD
    origins: ["https://example.com"],
    // GOOD
    origin: ["https://example.com"],
  }
});

注意

credentials: true を設定する場合は、origin: "*" を使用できません。

// THIS WON'T WORK
const io = new Server(httpServer, {
  cors: {
    origin: "*",
    credentials: true
  }
});

ブラウザのコンソールには、次のようなエラーが表示されます。

クロスオリジンリクエストがブロックされました: 同一オリジンポリシーにより、'.../socket.io/?EIO=4&transport=polling&t=NvQfU77' のリモートリソースの読み取りが許可されていません。(理由: CORS ヘッダー 'Access-Control-Allow-Origin' が '*' の場合、資格情報はサポートされていません)

ドメインのリストを提供する（推奨される解決策）か、以下の方法を使用する必要があります。

const io = new Server(httpServer, {
  cors: {
    origin: (_req, callback) => {
      callback(null, true);
    },
    credentials: true
  }
});

その場合、origin: "*" や origin: true と同様に、クロスオリジンリソースシェアリング (CORS) によって提供されるセキュリティを事実上無効にすることに注意してください。どのドメインからでもサーバーにアクセスできるようになります。注意して使用してください。

`httpCompression`

v1.4.0 で追加されました

デフォルト値: true

HTTP ロングポーリングトランスポートの圧縮を有効にするかどうか。

httpCompression が false に設定されている場合、HTTP ロングポーリングリクエストで接続が確立されると、送信時に使用される compress フラグ (socket.compress(true).emit(...)) は無視されます。

Node.js の zlib モジュールのすべてのオプションがサポートされています。

例

const io = new Server(httpServer, {
  httpCompression: {
    // Engine.IO options
    threshold: 2048, // defaults to 1024
    // Node.js zlib options
    chunkSize: 8 * 1024, // defaults to 16 * 1024
    windowBits: 14, // defaults to 15
    memLevel: 7, // defaults to 8
  }
});

`maxHttpBufferSize`

デフォルト値: 1e6 (1 MB)

ソケットを閉じる前に、単一のメッセージがどれだけのバイト数になるかを定義します。必要に応じて、この値を増減できます。

const io = new Server(httpServer, {
  maxHttpBufferSize: 1e8
});

ws パッケージの maxPayload オプションと一致します。

`perMessageDeflate`

履歴

バージョン	変更
v3.0.0	permessage-deflate 拡張機能はデフォルトで無効になりました。
v1.4.0	最初の実装。

デフォルト値: false

WebSocket トランスポートで permessage-deflate 拡張機能を有効にするかどうか。この拡張機能は、パフォーマンスとメモリ消費の点で大きなオーバーヘッドを追加することが知られているため、本当に必要な場合にのみ有効にすることをお勧めします。

perMessageDeflate が false（デフォルト）に設定されている場合、WebSocket で接続が確立されると、送信時に使用される compress フラグ (socket.compress(true).emit(...)) は無視されます。permessage-deflate 拡張機能はメッセージごとに有効にすることができないためです。

ws モジュールのすべてのオプションがサポートされています。

const io = new Server(httpServer, {
  perMessageDeflate: {
    threshold: 2048, // defaults to 1024

    zlibDeflateOptions: {
      chunkSize: 8 * 1024, // defaults to 16 * 1024
    },

    zlibInflateOptions: {
      windowBits: 14, // defaults to 15
      memLevel: 7, // defaults to 8
    },

    clientNoContextTakeover: true, // defaults to negotiated value.
    serverNoContextTakeover: true, // defaults to negotiated value.
    serverMaxWindowBits: 10, // defaults to negotiated value.

    concurrencyLimit: 20, // defaults to 10
  }
});

`pingInterval`

デフォルト値: 25000

この値は、サーバーとクライアント間の接続がまだ生きているかどうかを定期的にチェックするハートビートメカニズムで使用されます。

サーバーは pingInterval ミリ秒ごとに ping パケットを送信し、クライアントが pingTimeout ミリ秒以内に pong で応答しない場合、サーバーは接続が閉じていると見なします。

同様に、クライアントがサーバーから pingInterval + pingTimeout ミリ秒以内に ping パケットを受信しない場合、クライアントも接続が閉じていると見なします。

どちらの場合も、切断理由は次のようになります: ping timeout

socket.on("disconnect", (reason) => {
  console.log(reason); // "ping timeout"
});

注意

1000（1 秒あたり 1 つのハートビート）のような小さい値を使用すると、サーバーに負荷がかかり、数千のクライアントが接続されていると顕著になる可能性があります。

`pingTimeout`

履歴

バージョン	変更
v4.0.0	`pingTimeout` のデフォルト値が `20000` ミリ秒になりました。
v2.1.0	デフォルトは `5000` ミリ秒です。
v1.0.0	デフォルトは `60000` ミリ秒です。

デフォルト値: 20000

上記を参照してください。

注意

小さい値を使用すると、一時的に応答しないサーバーが多くのクライアントの再接続をトリガーする可能性があります。

逆に、大きい値を使用すると、接続が切断されたことを検出するのに時間がかかります（pingInterval + pingTimeout が 60 秒を超える場合、React Native で警告が表示される場合があります）。

`transports`

デフォルト値: ["polling", "websocket"]

サーバー側で許可されている低レベルトランスポート。

WebTransport が有効になっている場合の例

const io = new Server({
  transports: ["polling", "websocket", "webtransport"]
});

WebTransport の例はこちらをご覧ください。

クライアント側の transports も参照してください。

`upgradeTimeout`

デフォルト値: 10000

これは、未完了のトランスポートアップグレードがキャンセルされるまでの遅延（ミリ秒）です。

`wsEngine`

デフォルト値: require("ws").Server (ソースコードはこちらにあります)

使用する WebSocket サーバー実装。ドキュメントはこちらをご覧ください。

例

const io = new Server(httpServer, {
  wsEngine: require("eiows").Server
});

Socket.IOサーバーオプション​

adapter​

cleanupEmptyChildNamespaces​

connectionStateRecovery​

connectTimeout​

parser​

path​

serveClient​

低レベルエンジンオプション​

addTrailingSlash​

allowEIO3​

allowRequest​

allowUpgrades​

cookie​

cors​

httpCompression​

maxHttpBufferSize​

perMessageDeflate​

pingInterval​

pingTimeout​

transports​

upgradeTimeout​

wsEngine​

Socket.IOサーバーオプション

`adapter`

`cleanupEmptyChildNamespaces`

`connectionStateRecovery`

`connectTimeout`

`parser`

`path`

`serveClient`

低レベルエンジンオプション

`addTrailingSlash`

`allowEIO3`

`allowRequest`

`allowUpgrades`

`cookie`

`cors`

`httpCompression`

`maxHttpBufferSize`

`perMessageDeflate`

`pingInterval`

`pingTimeout`

`transports`

`upgradeTimeout`

`wsEngine`