深入 engine.io-parser：socket.io 生态中引擎协议编解码器的实现剖析

engine.io-parser 是 socket.io 单仓中为 engine.io 协议提供数据包序列化/反序列化的核心模块，它同时被 engine.io 服务端 与 engine.io-client 客户端 引用，是 HTTP long-polling、WebSocket 与 WebTransport 三种传输层之下的统一"语言翻译官"。本文以 packages/engine.io-parser/Readme.md 为主线，结合 源码实现 与 engine.io 协议 v4 规范，完整讲解其四大 API、包类型编码规则、Node 与浏览器的双端差异，以及 WebTransport 的帧封装实现，帮助你在自定义客户端或排查实时通信问题时有据可依。

它是什么、在协议栈中的位置

根据 Readme 的说明，engine.io-parser 是 "the JavaScript parser for the engine.io protocol encoding"，即 engine.io 协议编码的 JavaScript 解析器，并且由 engine.io-client 和 engine.io 双方共享同一份实现。这种"双端同仓同源"的设计保证了客户端和服务端对报文的理解永远一致——从 packages/engine.io-parser/lib/index.ts 中可以看到它导出 protocol = 4，对应 Engine.IO 协议 v4 规范；协议 v4.1 新增的 WebTransport 支持则由同一个包内的编解码流（createPacketEncoderStream / createPacketDecoderStream）实现。

当前的包版本为 5.2.3（见 packages/engine.io-parser/package.json），运行环境要求 node >= 10.0.0，并同时提供 CJS 与 ESM 两套构建产物（main 指向 ./build/cjs/index.js，module 指向 ./build/esm/index.js，通过 exports 字段区分 import 与 require）。

独立使用：四大核心 API

Readme 的 "Standalone" 一节说明：解析器可以编解码单个包（packet）、多个包的载荷（payload），共四个方法：encodePacket、decodePacket、encodePayload、decodePayload。官方示例如下（继承自 Readme）：

const parser = require("engine.io-parser");
const data = Buffer.from([ 1, 2, 3, 4 ]);

parser.encodePacket({ type: "message", data }, encoded => {
  const decodedData = parser.decodePacket(encoded); // decodedData === data
});

这段代码把 { type: "message", data: Buffer.from([1, 2, 3, 4]) } 编码为二进制形式（Node 下 data 是 ArrayBuffer 视图且默认支持二进制时，直接透传原始数据），再解码回来得到与原数据相等的结果。

API 参数速查

以下参数说明完整继承自 Readme 的 "API" 章节，并结合 packages/engine.io-parser/lib/commons.ts 中的 TypeScript 类型定义补充了实际取值：

方法	作用	参数
encodePacket(packet, supportsBinary, cb)	编码单个包	packet：含 type 与 data 的对象，data 可以是 String、Number、Buffer、ArrayBuffer；supportsBinary：布尔值，当前传输是否支持二进制；cb(String | binary)：回调，返回编码后的包
decodePacket(encodedPacket, binaryType?)	解码单个包	encodedPacket：String 或 ArrayBuffer；binaryType：可选，取值 "nodebuffer" / "arraybuffer" / "blob"，决定二进制数据以何种形式返回（Node 下默认返回 Buffer/ArrayBuffer，浏览器下默认 ArrayBuffer，可选 Blob）
encodePayload(packets, cb)	编码多个包（payload）	包数组；回调返回编码后的 payload 字符串。其中包含二进制的包一律 base64 编码，base64 字符串在长度标记前带 b 前缀
decodePayload(payload, binaryType?)	解码 payload	字符串形式的 payload；新版实现直接返回 Packet[] 数组（见下文源码说明）

Readme 中 cb(type) 的记法表示回调函数携带一个 type 类型的参数。

从 Readme 示例看 payload 编解码

Readme "With browserify" 小节给出了一段跨包类型的完整示例，这里保留原样以便读者可直接理解 payload 级别的用法（注意 decodePayload 在 Readme 中演示的是回调风格，对应 engine.io 的 v3 协议解析器；当前 v4 解析器返回数组，调用方式略有不同，见下文测试用例部分）：

const parser = require("engine.io-parser");

const testBuffer = new Int8Array(10);
for (let i = 0; i < testBuffer.length; i++) testBuffer[i] = i;

const packets = [{ type: "message", data: testBuffer.buffer }, { type: "message", data: "hello" }];

parser.encodePayload(packets, encoded => {
  parser.decodePayload(encoded,
    (packet, index, total) => {
      const isLast = index + 1 == total;
      if (!isLast) {
        const buffer = new Int8Array(packet.data); // testBuffer
      } else {
        const message = packet.data; // "hello"
      }
    });
});

包模型：七种包类型与数字编码

所有编解码的地基是 packages/engine.io-parser/lib/commons.ts 中的包类型映射表：

包类型	编码	用途（对应 协议文档）
open	0	握手阶段
close	1	表示某个传输可以关闭
ping	2	心跳机制（v4 起由服务端发起）
pong	3	心跳机制
message	4	向对端发送数据
upgrade	5	传输升级流程
noop	6	传输升级流程

此外还定义了统一的错误包 ERROR_PACKET = { type: "error", data: "parser error" }，任何无法解析的内容都返回它，而不是抛出异常。同文件中的 Packet 接口还带有一个可选的 options 字段（含 compress 压缩标记与 WebSocket 预编码帧的缓存字段），后者供上层（如 socket.io 适配层）避免重复编码。

编码规则：文本包、二进制包与 \x1e 分隔符

单个包的编码

packages/engine.io-parser/lib/encodePacket.ts 中 encodePacket 的逻辑非常简洁，只有两条分支：

1. 若 data 是 ArrayBuffer 或 ArrayBuffer 视图：supportsBinary 为真时原样返回二进制数据；否则转成 Buffer 后 base64 编码，并加上 b 前缀（"b" + base64）。
2. 纯文本：返回 PACKET_TYPES[type] + (data || "")，即"类型数字 + 数据"，如 4hello。

解码端 packages/engine.io-parser/lib/decodePacket.ts 与之严格对称：

• 非字符串输入（Buffer/ArrayBuffer）→ 直接视为 message 包，二进制数据按 binaryType 归一化；
• 字符串首字符为 b → base64 解码为二进制 message 包；
• 首字符在类型表中 → 取 substring(1) 作为数据；
• 首字符不是合法类型（例如空串 "" 或 "a123"）→ 返回 { type: "error", data: "parser error" }。

这些行为在 test/index.ts 中有直接验证：

encodePacket({ type: "message", data: "test" }, true, (encodedPacket) => {
  expect(encodedPacket).to.eql("4test");
  expect(decodePacket(encodedPacket)).to.eql(packet);
});

expect(decodePacket("")).to.eql({ type: "error", data: "parser error" });
expect(decodePacket("a123")).to.eql({ type: "error", data: "parser error" });

这与 协议 v4 规范 中 "Packet encoding" 一节完全一致：WebSocket 传输下每个包独占一个帧，格式为 <packet type>[<data>]，二进制原样发送；HTTP long-polling 传输下二进制必须 base64 编码并加 b 前缀。

payload 级编码与 \x1e 分隔符

packages/engine.io-parser/lib/index.ts 中定义了 payload 的拼接与拆分：

const SEPARATOR = String.fromCharCode(30); // 即 \x1e，record separator

• encodePayload(packets, callback)：先保存初始长度（注释说明编码过程中数组可能被追加），对每个包强制 supportsBinary = false 调用 encodePacket——也就是说 payload 中的二进制一律 base64 编码（这正是协议 v3→v4 的重要变更：统一处理方式，不再关心当前传输是否支持二进制，见 协议文档 History 一节），全部完成后用 \x1e 连接。
• decodePayload(encodedPayload, binaryType?)：按 \x1e 切分后逐段 decodePacket，一旦遇到 error 类型的包立即中断，返回 Packet[] 数组。

测试用例印证了拼接格式（test/index.ts）：

const packets = [
  { type: "open" },
  { type: "close" },
  { type: "ping", data: "probe" },
  { type: "pong", data: "probe" },
  { type: "message", data: "test" },
];
encodePayload(packets, (payload) => {
  expect(payload).to.eql("0\x1e1\x1e2probe\x1e3probe\x1e4test");
  expect(decodePayload(payload)).to.eql(packets);
});

即 <packet type>[<data>]\x1e<packet type>[<data>]...，与协议文档中 4hello\x1e2\x1e4world 的示例格式一致。选择 \x1e（record separator）而非"按字符计数"也是 v4 的刻意设计：字符计数在非 UTF-16 实现的语言中难以复刻（例如 € 的 UTF-16 长度与字节长度不一致），分隔符方案让多语言实现更容易对齐。

base64 编解码的兼容实现

Node 端直接使用 Buffer 的 base64 能力；浏览器端则依赖 packages/engine.io-parser/lib/contrib/base64-arraybuffer.ts 中手写的 base64 与 ArrayBuffer 互转实现（避免额外依赖）。这是该包"可在浏览器、Node.js 中无缝运行，并可运行在 HTML5 WebWorker 内"（Readme "Features" 一节）的关键之一。

平台差异：Node 与浏览器的双版本文件

Readme 提到二进制数据的编码目标"浏览器中是 ArrayBuffer 或 Blob，Node 中是 Buffer 或 ArrayBuffer"。这个双端差异是通过 TypeScript 的条件编译文件 + package.json 的 browser 字段实现的：

• packages/engine.io-parser/lib/encodePacket.ts 与 packages/engine.io-parser/lib/encodePacket.browser.ts
• packages/engine.io-parser/lib/decodePacket.ts 与 packages/engine.io-parser/lib/decodePacket.browser.ts

package.json 中的 browser 字段负责在打包（webpack、browserify 等）时把构建产物中的 Node 版本替换为浏览器版本：

"browser": {
  "./build/cjs/encodePacket.js": "./build/cjs/encodePacket.browser.js",
  "./build/cjs/decodePacket.js": "./build/cjs/decodePacket.browser.js"
}

两端的实现差异主要体现在二进制类型的处理上：

浏览器编码端（encodePacket.browser.ts）额外识别 Blob：支持二进制时 Blob/ArrayBuffer 原样返回；不支持时通过 FileReader.readAsDataURL 读取 base64 内容并加 b 前缀：

const encodeBlobAsBase64 = (data: Blob, callback) => {
  const fileReader = new FileReader();
  fileReader.onload = function () {
    const content = (fileReader.result as string).split(",")[1];
    callback("b" + (content || ""));
  };
  return fileReader.readAsDataURL(data);
};

解码端的 mapBinary 函数则负责把不同来源（HTTP long-polling、WebSocket、WebTransport）的二进制统一转换为调用者要求的 binaryType：Node 版支持 arraybuffer / nodebuffer（默认）两种形态，处理 Buffer（来自 long-polling）与 Uint8Array（来自 WebTransport）两种输入；浏览器版支持 blob / arraybuffer（默认），处理 ArrayBuffer（来自 long-polling 的 base64 或 WebSocket）与 Uint8Array（来自 WebTransport）。此外浏览器版对不支持 ArrayBuffer 的旧浏览器有兜底：返回 { base64: true, data } 这种延迟解码结构，把 base64 还原工作留给上层。

WebTransport 帧封装：createPacketEncoderStream / createPacketDecoderStream

协议 v4.1 引入 WebTransport 传输后，packages/engine.io-parser/lib/index.ts 新增了一对基于 TransformStream 的编解码流，这是 Readme 未覆盖但源码中实际存在的重要能力。

编码流 createPacketEncoderStream()：对每个包先调用 encodePacketToBinary（文本包转 UTF-8 字节，二进制包转 Uint8Array），再按 WebSocket 分帧格式的思路写一个长度头：

• 载荷 < 126 字节：1 字节头，低 7 位直接存长度；
• 126 ~ 65535 字节：3 字节头，首字节 126 + 2 字节长度；
• 更大：9 字节头，首字节 127 + 8 字节长度；
• 首字节最高位（0x80）标记载荷是二进制（1）还是纯文本（0）。

解码流 createPacketDecoderStream(maxPayload, binaryType)：内部维护一个四状态机（READ_HEADER → READ_EXTENDED_LENGTH_16 / READ_EXTENDED_LENGTH_64 → READ_PAYLOAD），用 concatChunks 处理跨 chunk 的头部切分；同时有两条安全防线——64 位扩展长度的高 32 位超过 JavaScript 安全整数范围（2^53 - 1）时输出 ERROR_PACKET，以及 expectedLength === 0 || expectedLength > maxPayload 时输出 ERROR_PACKET 并终止。这里的 maxPayload 正是握手响应中服务端下发的 maxPayload 值，用于限制单次数据块大小。

engine.io 服务端 对这两个 API 的使用印证了调用关系：packages/engine.io/lib/server.ts 中用 createPacketDecoderStream 包装 WebTransport 入站数据，packages/engine.io/lib/transports/webtransport.ts 中用 createPacketEncoderStream 处理出站。对应的编帧行为由 test/index.ts 断言，例如文本包 "1€" 编码后头部为 Uint8Array.of(5)（6 字节 UTF-8 载荷的 1 字节长度头），Uint8Array.of(1, 2, 3) 二进制包编码后头部为 Uint8Array.of(131)（0x80 | 3，最高位表示二进制）。

在 engine.io 传输层中的实际使用

从 packages/engine.io/lib/transports/polling.ts 源码结构看，HTTP long-polling 传输是 parser 的主要消费者：接收数据时调用 decodePayload 得到包数组后逐个回调，发送时把缓冲区内的包交给 encodePayload(packets, doWrite) 一次性写出——这正是"多个包拼接进单个 payload 以提升吞吐"（协议文档 "HTTP long-polling" 一节）的落地实现。同文件还能看到对 v3 解析器的分支兼容：老客户端走 parser_v3 的回调式 API，v4 客户端走数组式 API，说明该包与 server 端保持了协议版本的双轨兼容。

打包进浏览器：browserify 用法

Readme "With browserify" 一节说明了作为 CommonJS 模块的打包方式，步骤完整继承如下：

1. 安装解析器包：

   npm install engine.io-parser
   

2. 编写应用代码（即上文 payload 示例）；

3. 构建 bundle：

   $ browserify app.js > bundle.js
   

4. 在页面中引入：

   <script src="/path/to/bundle.js"></script>
   

需要注意，现代项目（webpack、Rollup、Vite 等）同样会读取 browser 字段做 Node/浏览器文件替换，因此该包在 ESM 与现代打包器中同样可用，当前版本已原生提供 ESM 入口。

测试与基准验证

Readme "Tests" 一节的说明结合 package.json 的 scripts 可具体化为：

npm test              # 完整流程：prettier 格式检查 + 双端 tsc 编译 + node 测试
npm run test:node     # 仅跑 Node 端测试：nyc mocha --import=tsx test/index.ts
npm run test:browser  # 浏览器端测试：zuul test/index.ts --no-coverage

test 脚本还支持 $BROWSERS=1 环境变量切换为浏览器测试。浏览器测试基于 zuul（需要 saucelabs 账号配置），而 test/index.ts 中通过 typeof TransformStream === "function" 做了能力探测——不支持 TransformStream 的旧环境会自动跳过 WebTransport 编解码流相关用例。测试文件顶部还有一行值得注意的注释：import "./node" 在浏览器测试中会被替换为 "./browser"（对应 package.json 的 browser 映射 "./test/node": "./test/browser"），保证同一套断言在双端运行。

除了功能测试，仓库还保留了基准脚本 benchmarks/index.js，用 benchmark 套件对比字符串包/二进制包的编包与编 payload 六类操作，可作为性能回归的参考手段（具体数值依赖运行环境，建议自行运行确认）。

小结

engine.io-parser 用极小的代码量承担了三件事：文本与二进制包在字符串/base64/原始字节之间的互转、payload 级多包拼接与 \x1e 分隔、以及面向 WebTransport 的 WebSocket 风格分帧流。理解它的类型编码表（0~6）、b base64 前缀、binaryType 归一化规则和 maxPayload 安全边界，就基本掌握了 engine.io 协议在传输层之下的全部编码细节；再配合 协议 v4 规范 与 v4 协议测试套件，足以支撑跨语言实现、协议兼容层开发或对实时通信链路的深度调试。