Socket.IO 事件发射器包 @socket.io/component-emitter 版本演进史：从 0.0.2 到 3.1.2 的发布记录与源码印证

本文以 History.md 为主线，完整梳理 @socket.io/component-emitter 这个事件发射器（Event Emitter）包的全部版本发布记录：2021 年引入类型化事件、2022 年 ESM 支持与 4.0.0 的破坏性变更、2024 年双 CommonJS/ESM 包结构的重构。读完后你将掌握每个版本变更的具体原因与影响，并能对照当前仓库源码（lib/cjs、lib/esm）验证这些历史决策在今天代码中的落点。

一、包的定位与当前版本

@socket.io/component-emitter 位于 packages/socket.io-component-emitter，是一个极简的事件发射器组件，为 Readme.md 所描述的 Socket.IO 生态提供事件模型基础：它提供 Emitter(obj) 构造函数（可同时作为 mixin）、on/once/off/emit/listeners/hasListeners 六个核心方法。History.md 开头标注该包是 component-emitter 项目的 fork，并加入了 Socket.IO 特有的 TypeScript 类型定义。

当前仓库快照中，package.json 声明的版本为 3.1.2，与 History.md 版本表的最新一条一致。包的入口通过三个字段分流模块系统：

"main":   "./lib/cjs/index.js",
"module": "./lib/esm/index.js",
"types":  "./lib/cjs/index.d.ts"

值得注意的是 types 字段指向的是 CommonJS 目录下的类型声明——这正是 3.1.2 版本修复内容的直接体现（见下文）。

二、正式版本记录（2021—2024）：逐版本解析

History.md 用一张版本表列出了五个现代版本，下面按时间线逐条解析，并给出仓库内的源码证据。

2.1 3.0.0（2021-10-14）：类型化事件 + 具名导出

两个变更：

特性：支持类型化事件（typed events）。 即通过 TypeScript 泛型把「事件名 → 载荷类型」绑定起来。这一特性在当前源码的 lib/esm/index.d.ts 中完整保留：

export class Emitter<
    ListenEvents extends EventsMap,
    EmitEvents extends EventsMap,
    ReservedEvents extends EventsMap = {}
    > {

三个泛型参数分别约束「可监听事件」「可发射事件」「保留事件」。类型工具 EventNames、EventParams、ReservedOrUserListener（lib/esm/index.d.ts）在此基础上推导出每个方法调用的精确参数类型；FallbackToUntypedListener 则是一个兼容处理：当推导结果坍缩为 never 时回退到无类型监听器签名。

破坏性变更：从默认导出改为具名导出。 History.md 原文给出的迁移示例必须原样保留：

// before
import Emitter from "@socket.io/component-emitter"

// after
import { Emitter } from "@socket.io/component-emitter"

当前源码印证了这一点：lib/cjs/index.js 中为 exports.Emitter = Emitter;，lib/esm/index.js 中为 export function Emitter(obj)，均只有具名导出，没有默认导出。

2.2 3.1.0（2022-04-17）：新增 ESM 版本

该版本为包提供了原生 ES Module 入口。对应到当前仓库，即 lib/esm/index.js 这份 ESM 实现，以及 package.json 中的 "module" 字段。从源码结构看，ESM 版本与 CJS 版本的函数逻辑完全一致（同样的 mixin、$ 前缀、emitReserved 别名），仅模块封装语法不同，属于典型的「双构建产物」布局。

2.3 4.0.0（2022-11-22）：emitReserved() 重命名为 _emitReserved()

这是版本表中唯一标注 BREAKING CHANGES 的 4.x 版本。History.md 原文：

emitReserved() is renamed to _emitReserved() in order to enable proper mangling.

目的是让压缩器（如 terser）能够对该方法名做 mangle（混淆改名）——下划线前缀的私有属性通常被压缩工具排除在 mangle 之外，但此处反其道而行之：去掉「公共 API 味道」的方法名可以在打包时与调用点一并改名，减小 bundle 体积。History.md 给出的新语法：

import { Emitter } from "@socket.io/component-emitter";

class MyEmitter extends Emitter {
  foo() {
    this._emitReserved("input");
  }
}

需要说明的一个版本细节：当前仓库快照停留在 3.x 线（3.1.2），其运行时源码中别名仍写作 emitReserved（lib/cjs/index.js 与 lib/esm/index.js 中的注释 // alias used for reserved events (protected method) 及 Emitter.prototype.emitReserved = Emitter.prototype.emit;），而类型声明中该方法为 protected emitReserved（lib/cjs/index.d.ts）。也就是说，在 3.1.x 线上，「保留事件」在运行时通过 emitReserved 别名暴露、在类型层面通过 protected 限制；4.0.0 的下划线改名属于另一条版本线。使用 4.x 时应以 History.md 中的 _emitReserved 写法为准。

2.4 3.1.1（2024-04-10）：双 CJS/ESM 打包方案重构

History.md 原文说明了重构动机：

This release contains a rework of the dual CommonJS/ES packages. Instead of relying on the .mjs file extension, which causes some problems, we will use two package.json files, one with "type": "commonjs" and the other with "type": "module".

即：不再依赖 .mjs 扩展名来标识 ESM 文件（该做法在部分 Node/打包器场景下产生兼容问题），改为用两份内嵌 package.json 各自声明模块类型。当前仓库中这一方案清晰可见：

• lib/cjs/package.json：{ "name": "@socket.io/component-emitter", "type": "commonjs" }
• lib/esm/package.json：{ "name": "@socket.io/component-emitter", "type": "module" }

两份文件同包名、同结构，仅 "type" 字段不同，Node 会按离文件最近的 package.json 判定模块语义。

2.5 3.1.2（2024-04-26）：类型声明指向 CommonJS

最新的修复条目：

Bug Fixes: point towards the CommonJS types

对应 package.json 中 "types": "./lib/cjs/index.d.ts"。由于 Node 的 CJS 解析路径优先命中根 package.json 的 types 字段，让类型声明指向 CJS 目录可保证在 CommonJS 环境下 IDE 与 tsc 拿到正确的模块解析结果。当前快照中 lib/cjs/index.d.ts 与 lib/esm/index.d.ts 内容一致，均包含完整的类型化 Emitter 类声明。

三、早期历史（0.0.2—1.3.0）：API 的成型过程

History.md 下半部分用经典 CHANGELOG 格式记录了包改名前（component-emitter）的完整演化。这些条目解释了许多当前源码中「看起来不起眼」的设计从何而来：

版本 / 日期	记录内容	对应当前源码的落点
1.3.0 / 2018-04-15	移除 bower 支持；在 exports 上暴露 emitter；避免使用 arguments 导致去优化（de-optimization）	lib/cjs/index.js 中 emit 用 new Array(arguments.length - 1) 手动展开参数，而非直接传递 arguments 对象——这是 V8 时代的经典优化规避手法
1.2.1 / 2016-04-18	支持客户端（浏览器）使用	双产物结构的前身
1.2.0 / 2014-02-12	事件名加 $ 前缀，以支持 Object.prototype 方法名作为事件名	lib/esm/index.js 中 this._callbacks['$' + event]。测试 test/emitter.js 专门验证了 emitter.on('constructor', ...) 与 emitter.on('__proto__', ...) 这类危险事件名可正常工作
1.1.3 / 2014-06-20	重新发布到 npm；补充 LICENSE 文件	当前包携带 LICENSE（MIT）
1.1.2 / 2014-02-10	包改名 "component-emitter"；更新 main 与 component 字段	package.json 中仍保留 component.scripts 声明
1.1.1 / 2013-12-01	修复 .once 内部添加 .on 监听器的问题；文档补充 Emitter#off()	lib/esm/index.js 中 once 的包装函数通过 on.fn = fn 保留原函数引用，使 off(event, 原函数) 能命中包装器
1.1.0 / 2013-10-20	增加 .addEventListener() 与 .removeEventListener() 别名	当前源码中 on/off 均挂了 DOM 风格别名（lib/cjs/index.js、L81-L84），即 off = removeListener = removeAllListeners = removeEventListener
1.0.1 / 2013-06-27	支持旧版 IE	—
1.0.0 / 2013-02-26	.off() 支持移除全部监听器	off() 零参数分支：this._callbacks = {}（lib/esm/index.js）
0.0.6 / 2012-10-08	初始化 this._callbacks 防止边界问题	各方法开头的惰性初始化 `this._callbacks = this._callbacks
0.0.5 / 2012-09-07	修复 Emitter.call(this) 用法	测试 test/emitter.js 中 Custom 构造函数正是以 Emitter.call(this) 模式验证继承场景
0.0.3 / 2012-07-11	新增 .listeners()；.has() 改名为 .hasListeners()	现网 API 名即来源于此改名
0.0.2 / 2012-06-28	修复 .off() 无法移除 .once() 注册的回调	对应 cb.fn === fn 的匹配逻辑（lib/esm/index.js）

此外还有一个未在 History.md 中单独列出、但源码中可验证的后续改进：off 在回调数组清空后会 delete 掉对应事件键以避免内存泄漏（lib/esm/index.js），test/emitter.js 中有「should remove event array to avoid memory leak」等两条专门测试。

四、三种使用方式的源码印证

History.md 的诸多条目最终都服务于 Readme.md 描述的三种用法，test/emitter.js 对全部三种方式均有覆盖：

1. 作为 Emitter 实例：

import { Emitter } from '@socket.io/component-emitter';

var emitter = new Emitter;
emitter.emit('something');

2. 作为 mixin（任意普通对象获得发射能力）：

var user = { name: 'tobi' };
Emitter(user);
user.emit('im a user');

对应 lib/esm/index.js：Emitter(obj) 在收到参数时走 mixin(obj)，将 Emitter.prototype 上的所有方法逐一复制到目标对象。

3. 作为原型 mixin：

Emitter(User.prototype);

测试中的 Custom 构造器（Emitter.call(this) + 原型链设置，test/emitter.js）则验证了 0.0.5 修复过的「构造函数内调用」路径。

五、在 Socket.IO monorepo 中的实际依赖方

History.md 记录的每次打包结构变更（3.1.0 的 ESM、3.1.1 的双 package.json）之所以重要，是因为该包被 monorepo 内多个核心包以版本范围 ~3.1.0 依赖：

• packages/socket.io-client/package.json（"@socket.io/component-emitter": "~3.1.0"）
• packages/engine.io-client/package.json（"@socket.io/component-emitter": "~3.1.0"）
• packages/socket.io-parser/package.json（"@socket.io/component-emitter": "~3.1.0"）

客户端包（socket.io-client、engine.io-client）同时面向浏览器 ESM 打包与 Node CJS 环境，这正是 3.1.1 放弃 .mjs 方案、改用双 package.json 的直接受益场景：webpack/rollup 走 module 字段拿 ESM 产物，Node CJS 走 main 字段拿 CommonJS 产物，互不干扰。

六、查看与运行方式

• 查看完整发布记录：packages/socket.io-component-emitter/History.md
• 查看 API 文档与安装说明：packages/socket.io-component-emitter/Readme.md，安装命令为 npm i @socket.io/component-emitter
• 运行测试：包内 package.json 的 test 脚本为 mocha --require should --reporter spec，测试文件为 test/emitter.js
• 对照双模块产物：lib/cjs/index.js、lib/esm/index.js 及各自的 package.json

版本适配提示：History.md 同时覆盖 4.x 与 3.x 两条线，而当前仓库快照为 3.1.2。若项目锁定 ~3.1.0（如同 monorepo 内的依赖声明），运行时保留事件别名是 emitReserved，且 lib/*/index.d.ts 中以 protected emitReserved 提供类型约束；若升级到 4.x，则应按 History.md 的 4.0.0 条目改用 _emitReserved 写法，并注意 3.0.0 起必须使用具名导入 import { Emitter } from ...。