Skip to main content
Version: 4.x

客户端选项

IO 工厂选项​

¥IO factory options

forceNew​

默认值：false

¥Default value: false

是否创建新的 Manager 实例。

¥Whether to create a new Manager instance.

Manager 实例负责与服务器的底层连接（通过 HTTP 长轮询或 WebSocket 建立）。它处理重新连接逻辑。

¥A Manager instance is in charge of the low-level connection to the server (established with HTTP long-polling or WebSocket). It handles the reconnection logic.

Socket 实例是用于向服务器发送事件以及从服务器接收事件的接口。它属于给定的 namespace。

¥A Socket instance is the interface which is used to sends events to — and receive events from — the server. It belongs to a given namespace.

一个 Manager 可以附加到多个 Socket 实例。

¥A single Manager can be attached to several Socket instances.

以下示例将为 3 个 Socket 实例（一个 WebSocket 连接）重用同一个 Manager 实例：

¥The following example will reuse the same Manager instance for the 3 Socket instances (one single WebSocket connection):

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product"); // the "product" namespace
const orderSocket = io("https://example.com/order"); // the "order" namespace

以下示例将创建 3 个不同的 Manager 实例（从而创建 3 个不同的 WebSocket 连接）：

¥The following example will create 3 different Manager instances (and thus 3 distinct WebSocket connections):

const socket = io("https://example.com"); // the main namespace
const productSocket = io("https://example.com/product", { forceNew: true }); // the "product" namespace
const orderSocket = io("https://example.com/order", { forceNew: true }); // the "order" namespace

重用现有的命名空间也会每次创建一个新的管理器：

¥Reusing an existing namespace will also create a new Manager each time:

const socket1 = io(); // 1st manager
const socket2 = io(); // 2nd manager
const socket3 = io("/admin"); // reuse the 1st manager
const socket4 = io("/admin"); // 3rd manager

multiplex​

默认值：true

¥Default value: true

与 forceNew 相反：是否重用现有的 Manager 实例。

¥The opposite of forceNew: whether to reuse an existing Manager instance.

const socket = io(); // 1st manager
const adminSocket = io("/admin", { multiplex: false }); // 2nd manager

底层引擎选项​

¥Low-level engine options

info

这些设置将由连接到同一管理器的所有 Socket 实例共享。

¥These settings will be shared by all Socket instances attached to the same Manager.

addTrailingSlash​

v4.6.0 中添加

¥Added in v4.6.0

默认添加的尾部斜杠现在可以禁用：

¥The trailing slash which was added by default can now be disabled:

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

const socket = io("https://example.com", {
  addTrailingSlash: false
});

在上面的示例中，请求 URL 将为 https://example.com/socket.io 而不是 https://example.com/socket.io/。

¥In the example above, the request URL will be https://example.com/socket.io instead of https://example.com/socket.io/.

autoUnref​

v4.0.0 中添加

¥Added in v4.0.0

默认值：false

¥Default value: false

将 autoUnref 设置为 true 时，如果事件系统中没有其他活动计时器/TCP 套接字（即使客户端已连接），Socket.IO 客户端将允许程序退出：

¥With autoUnref set to true, the Socket.IO client will allow the program to exit if there is no other active timer/TCP socket in the event system (even if the client is connected):

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

const socket = io({
  autoUnref: true
});

也可以看看：https://nodejs.cn/api/timers.html#timeoutunref

¥See also: https://nodejs.cn/api/timers.html#timeoutunref

closeOnBeforeunload​

History
版本变化
v4.7.1该选项现在默认为 false。
v4.1.0首次实现。

默认值：false

¥Default value: false

当浏览器中触发 beforeunload 事件时是否（静默）关闭连接。

¥Whether to (silently) close the connection when the beforeunload event is emitted in the browser.

当此选项设置为 false（默认值）时，当用户在 Firefox 上重新加载页面时，Socket 实例将触发 disconnect 事件：

¥When this option is set to false (the default value), the Socket instance will emit a disconnect event when the user reloads the page on Firefox:

Example with Firefox when closeOnBeforeunload is set to false

note

此行为特定于 Firefox，在其他浏览器上，当用户重新加载页面时，Socket 实例不会触发任何 disconnect 事件。

¥This behavior is specific to Firefox, on other browsers the Socket instance will not emit any disconnect event when the user reloads the page.

当此选项设置为 true 时，所有浏览器将具有相同的行为（重新加载页面时没有 disconnect 事件）：

¥When this option is set to true, all browsers will have the same behavior (no disconnect event when reloading the page):

Example with Firefox when closeOnBeforeunload is set to true

caution

如果你在应用中使用 beforeunload 事件 ("你确定要离开此页面吗？")，建议将此选项保留为 false。

¥If you use the beforeunload event in your application ("are you sure that you want to leave this page?"), it is recommended to leave this option to false.

请查看 这个问题 了解更多信息。

¥Please check this issue for more information.

extraHeaders​

默认值：*

¥Default value: -

附加标头（然后在服务器端的 socket.handshake.headers 对象中找到）。

¥Additional headers (then found in socket.handshake.headers object on the server-side).

示例：

¥Example:

客户端

¥Client

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

const socket = io({
  extraHeaders: {
    "my-custom-header": "1234"
  }
});

服务器

¥Server

io.on("connection", (socket) => {
  console.log(socket.handshake.headers); // an object containing "my-custom-header": "1234"
});
caution

在浏览器环境中，如果仅启用 WebSocket 传输，则 extraHeaders 选项将被忽略，因为浏览器中的 WebSocket API 不允许提供自定义标头。

¥In a browser environment, the extraHeaders option will be ignored if you only enable the WebSocket transport, since the WebSocket API in the browser does not allow providing custom headers.

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

const socket = io({
  transports: ["websocket"],
  extraHeaders: {
    "my-custom-header": "1234" // ignored
  }
});

不过，这可以在 Node.js 或 React-Native 中工作。

¥This will work in Node.js or in React-Native though.

文档：WebSocket API

¥Documentation: WebSocket API

forceBase64​

默认值：false

¥Default value: false

是否对通过 WebSocket 发送的二进制内容强制进行 Base64 编码（对于 HTTP 长轮询始终启用）。

¥Whether to force base64 encoding for binary content sent over WebSocket (always enabled for HTTP long-polling).

path​

默认值：/socket.io/

¥Default value: /socket.io/

它是在服务器端捕获的路径的名称。

¥It is the name of the path that is captured on the server side.

caution

服务器和客户端值必须匹配（除非你在两者之间使用路径重写代理）。

¥The server and the client values must match (unless you are using a path-rewriting proxy in between).

客户端

¥Client

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

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

服务器

¥Server

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

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

请注意，这与 URI 中的路径不同，后者代表 命名空间。

¥Please note that this is different from the path in the URI, which represents the Namespace.

示例：

¥Example:

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

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

  • Socket 实例附加到 "order" 命名空间

    ¥the Socket instance is attached to the "order" Namespace

  • HTTP 请求将如下所示：GET https://example.com/my-custom-path/?EIO=4&transport=polling&t=ML4jUwU

    ¥the HTTP requests will look like: GET https://example.com/my-custom-path/?EIO=4&transport=polling&t=ML4jUwU

protocols​

v2.0.0 中添加

¥Added in v2.0.0

默认值：*

¥Default value: -

单个协议字符串或协议字符串数组。这些字符串用于指示子协议，以便单个服务器可以实现多个 WebSocket 子协议（例如，你可能希望一台服务器能够根据指定的协议处理不同类型的交互）。

¥Either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols (for example, you might want one server to be able to handle different types of interactions depending on the specified protocol).

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

const socket = io({
  transports: ["websocket"],
  protocols: ["my-protocol-v1"]
});

服务器：

¥Server:

io.on("connection", (socket) => {
  const transport = socket.conn.transport;
  console.log(transport.socket.protocol); // prints "my-protocol-v1"
});

参考：

¥References:

query​

默认值：*

¥Default value: -

附加查询参数（然后在服务器端的 socket.handshake.query 对象中找到）。

¥Additional query parameters (then found in socket.handshake.query object on the server-side).

示例：

¥Example:

客户端

¥Client

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

const socket = io({
  query: {
    x: 42
  }
});

服务器

¥Server

io.on("connection", (socket) => {
  console.log(socket.handshake.query); // prints { x: "42", EIO: "4", transport: "polling" }
});

查询参数在会话期间无法更新，因此在客户端更改 query 仅在当前会话关闭并创建新会话时才有效：

¥The query parameters cannot be updated for the duration of the session, so changing the query on the client-side will only be effective when the current session gets closed and a new one is created:

socket.io.on("reconnect_attempt", () => {
  socket.io.opts.query.x++;
});

注意：以下查询参数是保留的，不能在你的应用中使用：

¥Note: the following query parameters are reserved and can't be used in your application:

  • EIO：协议版本（当前为 "4"）

    ¥EIO: the version of the protocol (currently, "4")

  • transport：传输名称（"polling" 或 "websocket"）

    ¥transport: the transport name ("polling" or "websocket")

  • sid：会话 ID

    ¥sid: the session ID

  • j：如果传输正在轮询但需要 JSONP 响应

    ¥j: if the transport is polling but a JSONP response is required

  • t：用于缓存清除的散列时间戳

    ¥t: a hashed-timestamp used for cache-busting

rememberUpgrade​

默认值：false

¥Default value: false

如果为 true 并且之前与服务器的 WebSocket 连接成功，则连接尝试将绕过正常升级过程并首先尝试 WebSocket。发生传输错误后的连接尝试将使用正常的升级过程。建议你仅在使用 SSL/TLS 连接时或者你知道你的网络不会阻止 Websocket 时才打开此功能。

¥If true and if the previous WebSocket connection to the server succeeded, the connection attempt will bypass the normal upgrade process and will initially try WebSocket. A connection attempt following a transport error will use the normal upgrade process. It is recommended you turn this on only when using SSL/TLS connections, or if you know that your network does not block websockets.

timestampParam​

默认值："t"

¥Default value: "t"

用作时间戳键的查询参数的名称。

¥The name of the query parameter to use as our timestamp key.

timestampRequests​

默认值：true

¥Default value: true

是否向每个请求添加时间戳查询参数（用于缓存清除）。

¥Whether to add the timestamp query param to each request (for cache busting).

transportOptions​

v2.0.0 中添加

¥Added in v2.0.0

默认值：{}

¥Default value: {}

特定于运输的选项。

¥Transport-specific options.

示例：

¥Example:

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

const socket = io({
  path: "/path-for-http-long-polling/",
  transportOptions: {
    websocket: {
      path: "/path-for-websocket/"
    }
  }
});

transports​

History
版本变化
v4.7.0添加了 webtransport。
v1.0.0首次实现。

默认值：["polling", "websocket", "webtransport"]

¥Default value: ["polling", "websocket", "webtransport"]

可以通过以下方式建立与 Socket.IO 服务器的底层连接：

¥The low-level connection to the Socket.IO server can either be established with:

  • HTTP 长轮询：连续的 HTTP 请求（POST 用于写入，GET 用于读取）

    ¥HTTP long-polling: successive HTTP requests (POST for writing, GET for reading)

  • WebSocket

  • WebTransport

以下示例禁用 HTTP 长轮询传输：

¥The following example disables the HTTP long-polling transport:

const socket = io("https://example.com", { transports: ["websocket"] });

注意：在这种情况下，服务器端不需要粘性会话（更多信息 此处）。

¥Note: in that case, sticky sessions are not required on the server side (more information here).

默认情况下，首先建立 HTTP 长轮询连接，然后尝试升级到 WebSocket（解释 此处）。你可以首先使用 WebSocket：

¥By default, the HTTP long-polling connection is established first, and then an upgrade to WebSocket is attempted (explanation here). You can use WebSocket first with:

const socket = io("https://example.com", {
  transports: ["websocket", "polling"] // use WebSocket first, if available
});

socket.on("connect_error", () => {
  // revert to classic upgrade
  socket.io.opts.transports = ["polling", "websocket"];
});

一个可能的缺点是，只有在 WebSocket 连接无法建立时才会检查 CORS 配置 的有效性。

¥One possible downside is that the validity of your CORS configuration will only be checked if the WebSocket connection fails to be established.

upgrade​

默认值：true

¥Default value: true

客户端是否应尝试将传输从 HTTP 长轮询升级为更好的传输。

¥Whether the client should try to upgrade the transport from HTTP long-polling to something better.

withCredentials​

History
版本变化
v4.7.0Node.js 客户端现在支持 withCredentials 设置。
v3.0.0withCredentials 现在默认为 false。
v1.0.0首次实现。

默认值：false

¥Default value: false

是否应发送跨站点请求，包括 cookie、授权标头或 TLS 客户端证书等凭据。设置 withCredentials 对同站点请求没有影响。

¥Whether the cross-site requests should be sent including credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests.

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

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

服务器需要发送正确的 Access-Control-Allow-* 标头以允许连接：

¥The server needs to send the right Access-Control-Allow-* headers to allow the connection:

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

const httpServer = createServer();
const io = new Server(httpServer, {
  cors: {
    origin: "https://my-frontend.com",
    credentials: true
  }
});
caution

当设置 withCredentials 至 true 时，不能使用 origin: *。这将触发以下错误：

¥You cannot use origin: * when setting withCredentials to true. This will trigger the following error:

跨源请求被阻止：同源策略不允许读取“.../socket.io/?EIO=4&transport=polling&t=NvQfU77”处的远程资源。（原因：如果 CORS 标头“Access-Control-Allow-Origin”为“*”，则不支持凭据）

¥Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at ‘.../socket.io/?EIO=4&transport=polling&t=NvQfU77’. (Reason: Credential is not supported if the CORS header ‘Access-Control-Allow-Origin’ is ‘*’)

文档：

¥Documentation:

info

从版本 4.7.0 开始，当将 withCredentials 选项设置为 true 时，Node.js 客户端现在将在 HTTP 请求中包含 cookie，从而更轻松地在基于 cookie 的粘性会话中使用它。

¥Starting with version 4.7.0, when setting the withCredentials option to true, the Node.js client will now include the cookies in the HTTP requests, making it easier to use it with cookie-based sticky sessions.

Node.js 特定选项​

¥Node.js-specific options

支持以下选项：

¥The following options are supported:

  • agent

  • pfx

  • key

  • passphrase

  • cert

  • ca

  • ciphers

  • rejectUnauthorized

请参考 Node.js 文档：

¥Please refer to the Node.js documentation:

自签名证书示例：

¥Example with a self-signed certificate:

客户端

¥Client

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

const socket = io("https://example.com", {
  ca: readFileSync("./cert.pem")
});

服务器

¥Server

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./cert.pem"),
  key: readFileSync("./key.pem")
});
const io = new Server(httpServer);

客户端证书身份验证示例：

¥Example with client-certificate authentication:

客户端

¥Client

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

const socket = io("https://example.com", {
  ca: readFileSync("./server-cert.pem"),
  cert: readFileSync("./client-cert.pem"),
  key: readFileSync("./client-key.pem"),
});

服务器

¥Server

import { readFileSync } from "fs";
import { createServer } from "https";
import { Server } from "socket.io";

const httpServer = createServer({
  cert: readFileSync("./server-cert.pem"),
  key: readFileSync("./server-key.pem"),
  requestCert: true,
  ca: [
    readFileSync("client-cert.pem")
  ]
});
const io = new Server(httpServer);
caution

rejectUnauthorized 是仅 Node.js 的选项，它不会绕过浏览器中的安全检查：

¥rejectUnauthorized is a Node.js-only option, it will not bypass the security check in the browser:

Security warning in the browser

管理者选项​

¥Manager options

info

这些设置将由连接到同一管理器的所有 Socket 实例共享。

¥These settings will be shared by all Socket instances attached to the same Manager.

autoConnect​

默认值：true

¥Default value: true

创建时是否自动连接。如果设置为 false，则需要手动连接：

¥Whether to automatically connect upon creation. If set to false, you need to manually connect:

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

const socket = io({
  autoConnect: false
});

socket.connect();
// or
socket.io.open();

parser​

v2.2.0 中添加

¥Added in v2.2.0

默认值：require("socket.io-parser")

¥Default value: require("socket.io-parser")

用于编组/解组数据包的解析器。请参阅 此处 了解更多信息。

¥The parser used to marshall/unmarshall packets. Please see here for more information.

randomizationFactor​

默认值：0.5

¥Default value: 0.5

重新连接时使用的随机化因子（例如，以便客户端在服务器崩溃后不会在完全相同的时间重新连接）。

¥The randomization factor used when reconnecting (so that the clients do not reconnect at the exact same time after a server crash, for example).

使用默认值的示例：

¥Example with the default values:

  • 第一次重新连接尝试发生在 500 到 1500 毫秒之间 (1000 * 2^0 * (<something between -0.5 and 1.5>))

    ¥1st reconnection attempt happens between 500 and 1500 ms (1000 * 2^0 * (<something between -0.5 and 1.5>))

  • 第二次重新连接尝试发生在 1000 到 3000 毫秒之间 (1000 * 2^1 * (<something between -0.5 and 1.5>))

    ¥2nd reconnection attempt happens between 1000 and 3000 ms (1000 * 2^1 * (<something between -0.5 and 1.5>))

  • 第三次重新连接尝试发生在 2000 到 5000 毫秒之间 (1000 * 2^2 * (<something between -0.5 and 1.5>))

    ¥3rd reconnection attempt happens between 2000 and 5000 ms (1000 * 2^2 * (<something between -0.5 and 1.5>))

  • 下一次重新连接尝试发生在 5000 毫秒后

    ¥next reconnection attempts happen after 5000 ms

reconnection​

默认值：true

¥Default value: true

是否启用重连。如果设置为 false，则需要手动重新连接：

¥Whether reconnection is enabled or not. If set to false, you need to manually reconnect:

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

const socket = io({
  reconnection: false
});

const tryReconnect = () => {
  setTimeout(() => {
    socket.io.open((err) => {
      if (err) {
        tryReconnect();
      }
    });
  }, 2000);
}

socket.io.on("close", tryReconnect);

reconnectionAttempts​

默认值：Infinity

¥Default value: Infinity

放弃之前尝试重新连接的次数。

¥The number of reconnection attempts before giving up.

reconnectionDelay​

默认值：1000

¥Default value: 1000

重新连接之前的初始延迟（以毫秒为单位）（受 randomizationFactor 值影响）。

¥The initial delay before reconnection in milliseconds (affected by the randomizationFactor value).

reconnectionDelayMax​

默认值：5000

¥Default value: 5000

两次重新连接尝试之间的最大延迟。每次尝试都会使重新连接延迟增加 2 倍。

¥The maximum delay between two reconnection attempts. Each attempt increases the reconnection delay by 2x.

timeout​

默认值：20000

¥Default value: 20000

每次连接尝试的超时（以毫秒为单位）。

¥The timeout in milliseconds for each connection attempt.

套接字选项​

¥Socket options

info

这些设置特定于给定的 Socket 实例。

¥These settings are specific to the given Socket instance.

ackTimeout​

v4.6.0 中添加

¥Added in v4.6.0

默认值：*

¥Default value: -

等待确认时使用的默认超时（以毫秒为单位）（不要与管理器在连接期间使用的现有 timeout 选项混淆）

¥The default timeout in milliseconds used when waiting for an acknowledgement (not to be mixed up with the already existing timeout option, which is used by the Manager during the connection)

auth​

v3.0.0 中添加

¥Added in v3.0.0

默认值：*

¥Default value: -

访问命名空间时发送的凭证（另请参见 此处）。

¥Credentials that are sent when accessing a namespace (see also here).

示例：

¥Example:

客户端

¥Client

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

const socket = io({
  auth: {
    token: "abcd"
  }
});

// or with a function
const socket = io({
  auth: (cb) => {
    cb({ token: localStorage.token })
  }
});

服务器

¥Server

io.on("connection", (socket) => {
  console.log(socket.handshake.auth); // prints { token: "abcd" }
});

当对命名空间的访问被拒绝时，你可以更新 auth 映射：

¥You can update the auth map when the access to the Namespace is denied:

socket.on("connect_error", (err) => {
  if (err.message === "invalid credentials") {
    socket.auth.token = "efgh";
    socket.connect();
  }
});

或者手动强制 Socket 实例重新连接：

¥Or manually force the Socket instance to reconnect:

socket.auth.token = "efgh";
socket.disconnect().connect();

retries​

v4.6.0 中添加

¥Added in v4.6.0

默认值：*

¥Default value: -

最大重试次数。超过限制，数据包将被丢弃。

¥The maximum number of retries. Above the limit, the packet will be discarded.

const socket = io({
  retries: 3,
  ackTimeout: 10000
});

// implicit ack
socket.emit("my-event");

// explicit ack
socket.emit("my-event", (err, val) => { /* ... */ });

// custom timeout (in that case the ackTimeout is optional)
socket.timeout(5000).emit("my-event", (err, val) => { /* ... */ });