socket.io engine.io-parser 版本演进与编码架构:从协议 v4 到 WebTransport 支持

本文以 engine.io-parser 变更日志 为主线,梳理该模块从 2.2.x 到 5.2.3 的完整版本脉络:协议 v4 的二进制编码变更、TypeScript 重写与 exports 字段引入、ESM/CJS 双产物打包修复,以及 WebTransport 帧头支持的落地过程,并结合仓库源码(encodePacket.ts、decodePacket.ts、index.ts)逐条印证各版本变更背后的实现细节,帮助你在升级依赖时判断每个版本对你项目的实际影响。

engine.io-parser 在 socket.io 中的位置

engine.io-parser 是 Engine.IO 协议的 JavaScript 编码器/解码器,被 engine.io 服务端与 engine.io-client 客户端共享。它负责把数据包(open/close/ping/pong/message/upgrade/noop)编解码为可传输的字符串或二进制形态,并支持多包 payload 的打包。当前仓库中的版本为 5.2.3(见 package.json),与变更日志顶部记录一致。

对外 API 由 index.ts 统一导出:encodePacket、encodePayload、decodePacket、decodePayload、createPacketEncoderStream、createPacketDecoderStream,以及协议版本号 protocol = 4。

版本历史总览

变更日志开头的版本总表完整记录了 2019 年 9 月至 2024 年 7 月间的发布历史:

版本	发布日期	备注
5.2.3	2024 年 7 月
5.2.2	2024 年 2 月
5.2.1	2023 年 8 月
5.2.0	2023 年 7 月
5.1.0	2023 年 6 月
5.0.7	2023 年 5 月
5.0.6	2023 年 1 月
5.0.5	2023 年 1 月
5.0.4	2022 年 4 月
5.0.3	2022 年 1 月
5.0.2	2021 年 11 月
5.0.1	2021 年 10 月
5.0.0	2021 年 10 月	重大版本:TypeScript 重写
4.0.3	2021 年 8 月
4.0.2	2020 年 12 月
2.2.1	2020 年 9 月	来自 2.2.x 分支
4.0.1	2020 年 9 月
4.0.0	2020 年 9 月	重大版本:Engine.IO 协议 v4
2.2.0	2019 年 9 月

从时间线可以看出三条清晰的演进主线:4.0.0 是协议层的重大变更(对应 Engine.IO v4 协议),5.0.0 是工程化的重大变更(TypeScript 重写 + 新 exports 字段),5.1.0–5.2.3 是传输层的重大变更(WebTransport 编解码)。下面逐一展开。

4.0.0:协议 v4 的二进制编码变更(2020-09-08)

变更日志中技术密度最高的部分是 4.0.0 的发布说明:该版本包含 Engine.IO 协议 v4 所需的全部变更(协议细节可参见仓库内 v4 协议文档)。v3 与 v4 之间最核心的差异是:v4 不再对二进制包做长度前缀包裹,而是原样发送,文本与二进制混合 payload 改用分隔符拼接。日志给出了四组对照示例,值得完整保留:

1. encodePacket 处理字符串:

• 输入:{ type: "message", data: "hello" }
• v3 输出:"4hello"
• v4 输出:"4hello"(不变)

2. encodePacket 处理二进制:

• 输入:{ type: "message", data: <Buffer 01 02 03> }
• v3 输出:<Buffer 04 01 02 03>(在数据前插入类型字节 04)
• v4 输出:<Buffer 01 02 03>(原样,无任何转换)

3. encodePayload 处理多个字符串包:

• 输入:[ { type: 'message', data: 'hello' }, { type: 'message', data: '€€€' } ]
• v3 输出:"6:4hello4:4€€€"(逐包加 长度: 前缀)
• v4 输出:"4hello\x1e4€€€"(用 ASCII 30 分隔符拼接)

4. encodePayload 处理字符串与二进制混合:

• 输入:[ { type: 'message', data: 'hello' }, { type: 'message', data: <Buffer 01 02 03> } ]
• v3 输出:<Buffer 00 06 ff 34 68 65 6c 6c 6f 01 04 ff 04 01 02 03>(整体转为二进制并加帧头)
• v4 输出:"4hello\x1ebAQID"(文本包保持文本,二进制包以 base64 内联)

源码可以逐条印证这些行为:

• "分隔符拼接"体现在 index.ts 中的 SEPARATOR = String.fromCharCode(30)(取 ASCII 控制字符 RS 作为包间分隔符),encodePayload 将各包编码后 join(SEPARATOR),decodePayload 则先 split(SEPARATOR) 再逐包解码,遇到 error 类型包即中止。
• "二进制原样发送"体现在 encodePacket.ts 的 encodePacket 中:当 data 是 ArrayBuffer 或其视图时,若传输支持二进制(supportsBinary === true)则直接透传;仅在不支持二进制时才走 "b" + base64 编码——这正是 v4 输出 "4hello\x1ebAQID" 中 bAQID 的来源。
• 对应的解码逻辑在 decodePacket.ts:非字符串输入直接按 message 包处理二进制数据;字符串首字符为 b 时按 base64 解码;首字符不在 PACKET_TYPES_REVERSE 映射中(见 commons.ts 中 "0"~"6" 对应 open/close/ping/pong/message/upgrade/noop)则返回 ERROR_PACKET。

日志同时指出 4.0.0 的另外三个关键点:

• parser 从此无运行时依赖("the parser is now dependency-free"),用于减小浏览器 bundle 体积;
• Bug 修复 "keep track of the buffer initial length"——对应 index.ts 中 encodePayload 先保存 const length = packets.length 的写法,注释说明"编码过程中可能有包被追加到数组,因此必须保存初始长度";
• 功能 "restore the upgrade mechanism"——恢复 upgrade 包类型,即 PACKET_TYPES 中的 "upgrade": "5",用于传输升级(如 polling 升级到 WebSocket)时告知对端丢弃待处理的旧传输数据。

此外,变更日志保留了 4.0.0 的 alpha 阶段记录:4.0.0-alpha.0(2020-02-04)引入了"编码二进制包时移除 packet type"的破坏性变更({ type: 'message', data: <Buffer 01 02 03> } 从 v3 的 <Buffer 04 01 02 03> 变为 v4 的 <Buffer 01 02 03>),并修复了"properly decode binary packets";4.0.0-alpha.1(2020-05-19)完成了 v4 协议的整体实现。

5.0.0:TypeScript 重写与新 exports 字段(2021-10-04)

日志对 5.0.0 的说明只有两句,但影响深远:

This release includes the migration to TypeScript. The major bump is due to the new "exports" field in the package.json file.

即:代码从 JavaScript 迁移到 TypeScript 编写(当前仓库中 lib/ 下全部为 .ts 源码),而主版本号提升的原因并非行为变更,而是 package.json 中新增了 exports 字段。这一点可以从当前 package.json 得到印证:

• "main": "./build/cjs/index.js" + "module": "./build/esm/index.js" 保留了旧式入口;
• "exports": { "import": "./build/esm/index.js", "require": "./build/cjs/index.js" } 是 Node.js 的包入口点规范写法,按模块系统分别指向 ESM 与 CJS 产物;
• "types": "build/esm/index.d.ts" 指定类型声明位置。

这也解释了为什么 exports 字段会触发 major 版本:它对 Node.js 的模块解析行为(尤其是旧版本 Node 与某些打包器)可能产生兼容性影响,按语义化版本规范属于破坏性变更。

ESM/CJS 双产物的打包修复链(5.0.1 → 5.0.7)

5.0.0 之后的半年里,连续六个 patch/minor 版本几乎都在解决同一类问题:双产物(CJS + ESM)打包链路的可靠性。按时间倒序看这条修复链:

• 5.0.7(2023-05-24):CommonJS 构建产物现在也包含 TypeScript 类型声明,以兼容 moduleResolution: "node16"。从源码结构看,类型声明随 ESM/CJS 双构建产出(compile 脚本执行两次 tsc:默认配置加 tsconfig.esm.json),再经 postcompile.sh 把 support/package.cjs.json 与 support/package.esm.json 复制进各自构建目录,为两个子目录打上 "type" 标识——这是双产物共存的标准做法。
• 5.0.6(2023-01-16):纯流程修复——发布 5.0.5 前忘记执行 compile 脚本,导致 ESM 产物未包含最新代码。这是发布流程问题的直接记录。
• 5.0.2(2021-11-14):两条修复:在嵌套 package.json 中补充包名、修复 Vite 下 CommonJS 用户的构建。
• 5.0.1(2021-10-15):修复 Vite 构建问题,是 5.0.0 落地后第一个修补版本。
• 5.0.4(2022-04-30):补上 ESM import 缺失的文件扩展名(见 index.ts 中 from "./commons.js" 一类带 .js 后缀的导入,这正是 Node 原生 ESM 的强制要求);同时更新 RawData 的类型定义——现在 commons.ts 中 RawData 实际为 any,注释解释了原因:完整类型应为 string | Buffer | ArrayBuffer | ArrayBufferView | Blob,但 Blob 不存在于 Node.js 且需要额外引入 dom lib。
• 5.0.3(2022-01-17):日志条目为空,属于占位发布(通常用于同步 monorepo 发版)。

对使用者的实际意义:如果你在 2021 年 10 月后直接升级到 5.x,大概率会踩到 Vite/ESM 相关构建问题,5.0.2 之后的版本才算打包链路稳定;而在 moduleResolution: "node16" 的 TypeScript 项目中,5.0.7 之前的 CJS 导入可能拿不到类型声明。

二进制编解码的正确性修复(4.0.2、4.0.3、5.0.5)

穿插在这条打包修复链之间的,还有三个针对二进制数据处理正确性的修复:

4.0.3 — 尊重 TypedArray 的 offset 与 length(2021-08-29)。这是 toBuffer 逻辑的由来。看 encodePacket.ts 中 toBuffer 的实现:

const toBuffer = (
  data: ArrayBuffer | ArrayBufferView,
  forceBufferConversion: boolean,
) => {
  if (
    Buffer.isBuffer(data) ||
    (data instanceof Uint8Array && !forceBufferConversion)
  ) {
    return data;
  } else if (data instanceof ArrayBuffer) {
    return Buffer.from(data);
  } else {
    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
  }
};

关键点在最后一个分支:对于 Int8Array、Uint16Array 或带偏移量的 Uint8Array 等视图,必须用 Buffer.from(data.buffer, data.byteOffset, data.byteLength) 带上 byteOffset 和 byteLength,否则会取到整个底层 buffer 的全部字节——修复前,视图视图之外的"脏数据"可能被编码进包里。而 Buffer/无偏移 Uint8Array 则直接透传(forceBufferConversion 参数控制这条快路径,浏览器端强制走 base64 转换)。

4.0.2 — 将 base64-arraybuffer 补为生产依赖(2020-12-07)。浏览器端没有 Buffer,base64 编解码依赖 lib/contrib/base64-arraybuffer.ts 中的实现;该版本修复了依赖声明遗漏的问题,避免浏览器打包时缺依赖。

5.0.5 — 正确以 base64 编码空 buffer(对应 issue #131)。空二进制数据在 base64 路径下容易被误判为空字符串,此修复保证了 { type: "message", data: 空二进制 } 与空字符串报文不会在解码端混淆。浏览器端的 base64 路径可参考 encodePacket.browser.ts:Blob/ArrayBuffer/视图数据在 supportsBinary 为 false 时统一走 encodeBlobAsBase64,并带有 ArrayBuffer.isView 在 IE10 未定义时的降级判断。

WebTransport 支持的落地过程(5.1.0 → 5.2.3)

2023 年的四个版本完整记录了 WebTransport 传输支持在 parser 层的演进,日志表述简练,但源码可以还原全部细节:

5.1.0(2023-06-11)— 实现 WebTransport 相关的编码/解码。 在 index.ts 中体现为两个基于 TransformStream 的工厂函数:

• createPacketEncoderStream():把单个 Packet 编码后,先写出一个帧头再写出 payload。帧头格式借鉴了 WebSocket 的 payload length 设计:payload 长度 < 126 时用 1 字节表示;126 ≤ 长度 < 65536 时用 3 字节(首字节 126 + 2 字节长度);否则用 9 字节(首字节 127 + 8 字节长度)。帧头最高位(0x80)标记 payload 是文本(0)还是二进制(1)。
• createPacketDecoderStream(maxPayload, binaryType):一个带状态机(READ_HEADER → READ_EXTENDED_LENGTH_16/READ_EXTENDED_LENGTH_64 → READ_PAYLOAD)的流式解码器,处理跨 chunk 分帧、校验长度上限(expectedLength === 0 || expectedLength > maxPayload 时输出 ERROR_PACKET),并对 64 位扩展长度做了 JavaScript 安全整数(2^53-1)溢出保护。

5.2.0(2023-07-31)— 为每个 WebTransport chunk 添加头部。 即上面描述的"长度 + 文本/二进制标志"帧头方案,使接收端可以在字节流上无歧义地切分出一个个包。

5.2.1(2023-08-01)— WebTransport 帧格式微调。 日志只有一句"The format of the WebTransport frame has been slightly updated",属于发布后对帧格式的即时修正。

5.2.2(2024-02-05)与 5.2.3(2024-07-11)— TransformStream 类型修复。 连续两个版本都在处理同一个问题:TransformStream 是 Web 标准库类型,在 Node 环境需要正确导入/不对外暴露其类型声明,否则 TypeScript 用户会拿到错误的类型来源。5.2.3 是日志中记录的最新版本,也是当前仓库 package.json 中的实际版本。

测试侧同样有对应覆盖:test/index.ts 中对 createPacketEncoderStream 与 createPacketDecoderStream 各有多组用例(覆盖文本包、二进制包、126/127 扩展长度、maxPayload 超限、超大 payload 拒绝等场景),WebTransport 的端到端行为另由 engine.io 测试 与 engine.io-client 测试 验证。

早期版本与遗留修复(2.2.0、2.2.1、4.0.1)

变更日志还保留了 4.x 之前的少量记录:

• 2.2.0(2019-09-13):改用 Buffer.allocUnsafe 替代已废弃的 new Buffer,并因此放弃 Node.js 4 的支持(Buffer.allocUnsafe 自 v5.10.0 才引入)。这是典型的"安全 API 迁移连带最低版本提升"的决策。
• 2.2.1(2020-09-30):从 2.2.x 维护分支发布的补丁版,与 4.0.0 同期存在,供仍停留在 Engine.IO v3 协议的用户使用——这也解释了总表中 2.2.1 日期晚于 4.0.0 却排在后面的原因。
• 4.0.1(2020-09-10):使用 terser 兼容的分隔符表示方式。v3 时代分隔符可能以特殊字符字面量书写,压缩器会破坏它;4.0.1 之后统一为 String.fromCharCode(30) 这类运行时构造(即当前 index.ts 的写法,注释还引用了 Wikipedia 上 ASCII 分隔符条目),确保 minify 后字节值不变。

从变更日志看版本选择与升级建议

综合以上分析,这份变更日志给出了几份实用的"决策依据":

1. 跨大版本升级看两处:4.0.0 是协议语义变更(二进制编码方式、payload 拼接方式),升级时必须确认客户端与服务端同升;5.0.0 是包工程变更(exports 字段 + TS 重写),升级时关注的是构建工具链(Node 版本、打包器、moduleResolution)而非运行时行为。
2. 5.x 内的稳定起点是 5.0.2:5.0.1 之前的 Vite/ESM 问题、5.0.7 之前的 CJS 类型声明缺失,都是打包链路的坑;追求稳妥可直达 5.2.3(当前仓库版本)。
3. 浏览器 bundle 敏感的团队可以关注 4.0.0 起 parser 零依赖这一事实,以及 4.0.2 之后 base64-arraybuffer 的正确声明,两者共同决定了浏览器产物的体积与完整性。
4. 使用 WebTransport 的部署(参考 engine.io WebTransport 测试 与 示例)至少需要 5.1.0,而帧格式最终定型于 5.2.1,类型问题到 5.2.3 才完全收敛——跨 5.1.0/5.2.x 混部署时客户端与服务端的 parser 版本应保持一致,因为帧头格式在 5.2.1 发生过调整。

如需进一步核对任何一条版本说明,可直接对照 packages/engine.io-parser/CHANGELOG.md 原文,并结合上文给出的源码文件路径查看对应实现。