在 ES Modules 中导入 engine.io：engine.io ESM 导入示例的源码级解析

在 ES Modules 中导入 engine.io：engine.io ESM 导入示例的源码级解析

【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io

本篇技术指南围绕 engine.io 的 ESM 导入示例 展开，讲清“为什么一个 CommonJS 打包的engine.io包，能在 Node.js 的 ES Modules 里直接import”这一核心问题。读完你将掌握：如何用npm link把本地engine.io包接入示例工程、package.json中exports的import/require双条件是如何分流 ESM 与 CJS 消费者的，以及wrapper.mjs这个手写 ESM 适配层背后的完整导出面。

示例要解决什么问题

engine.io是 Socket.IO 底层的实时通信引擎，官方定位是“在客户端与服务器之间提供双向连接的基础设施”。它发布到 npm 的产物是CommonJS格式：编译目标由 tsconfig.json 中的"module": "commonjs"决定，main指向./build/engine.io.js（见 package.json）。

但现代 Node.js 项目越来越多地使用 ES Modules（在package.json中声明"type": "module"的文件使用import语法）。这个示例工程 packages/engine.io/examples/esm-import 的作用，就是验证并确保：即使engine.io的核心是 CJS，ESM 消费者也能以标准import方式正确拿到命名导出。

最小运行步骤（继承自示例 README）

示例自带的使用说明只有两条命令，直接可复制执行：

$ npm link ../.. $ node index.js

• npm link ../..：../..是相对于示例目录packages/engine.io/examples/esm-import/的上两级，即packages/engine.io（engine.io包根目录）。该命令把本地的engine.io包以符号链接的方式接入示例工程，使得import { Server } from "engine.io"解析到本地未发布的源码编译产物，而不是 npm 上的发布版。这样示例始终针对当前仓库的最新实现。
• node index.js：运行示例入口 index.js。

示例入口非常短，核心就是验证 ESM 命名导出能否被正确拿到：

import { Server } from "engine.io"; console.log(Server);

能打印出Server构造器（而非报错或undefined），即证明 ESM 导入路径工作正常。

"type": "module"与导入入口

示例工程的 package.json 里最关键的字段只有：

{ "name": "esm-import", "version": "0.0.1", "private": true, "type": "module" }

"type": "module"告诉 Node.js：该目录下所有.js文件按 ES Modules 处理。因此index.js里的import语句才合法。这里"private": true表明它是一个纯示例，不参与发布。

注意：ESM 对.js扩展名的模块类型解析依赖该字段，而 ESM 语法在 Node.js 中自 12.17.0 起才稳定可用——这是一般性前提，具体以你运行示例时的 Node 版本为准。

关键机制：exports的双条件分流

要让 CJS 包同时被require和import消费，engine.io在 package.json 中使用了exports条件字段：

"exports": { "types": "./build/engine.io.d.ts", "import": "./wrapper.mjs", "require": "./build/engine.io.js" }

• 当消费者用import（ESM）时，Node 走import条件，加载 wrapper.mjs；
• 当消费者用require（CJS）时，Node 走require条件，直接加载 CommonJS 构建产物build/engine.io.js；
• types条件则保证 TypeScript 消费者拿到类型声明build/engine.io.d.ts。

也就是说，ESM 消费者并不会直接import一个.js（CJS）文件，而是被“重定向”到一个专门书写的.mjs适配文件。这就是下一节的主角。

wrapper.mjs：手写 ESM 适配层

wrapper.mjs 全文如下：

export { Server, Socket, Transport, transports, listen, attach, parser, protocol, } from "./build/engine.io.js";

它做了一件简洁而关键的事：把 CJS 构建产物./build/engine.io.js上的命名成员，逐条re-export成 ESM 命名导出。因为构建产物是 CommonJS（module.exports是一个整体对象），Node 在 ESM 侧import一个 CJS 模块时，能否拿到稳定的命名导出取决于其对 CJS 模块的命名分析；用一个显式的.mjs转发层，可以把对外 API 面固定下来，避免import { Server }在不同 Node 版本/打包工具下出现undefined的差异。

这 8 个导出正是engine.io面向用户的核心 API，与 lib/engine.io.ts 的顶层导出相互对应：

• Server、Socket、Transport：核心类；
• transports：可用传输层集合；
• listen、attach：两个工厂式入口函数（下节展开）;
• parser：engine.io-parser的转发；
• protocol：协议版本号常量，export const protocol = parser.protocol。

从源码结构看，wrapper.mjs与lib/engine.io.ts的export列表保持一致（Server、transports、listen、attach、parser等），说明适配层就是按“源码对外导出面”1:1 复刻的，保证 ESM 与 CJS 两条路径拿到的 API 完全对称。

listen与attach的底层行为

理解了导入面之后，可以顺带看清这两个最常用入口在 lib/engine.io.ts 中的实现，帮助判断 ESM 导入拿到的listen/attach到底是什么：

• listen(port, options?, listenCallback?)（engine.io.ts）：内部先createServer创建一个“仅用于 WS 升级”的http.Server，对非升级请求返回501 Not Implemented；随后调用attach(server, options)把 engine 挂上去，并server.listen(port)开始监听，最后返回 engine 实例。注意它对options做了兼容——若传入的是函数，则把它当作listenCallback，options置空。
• attach(server, options)（engine.io.ts）：new Server(options)后调用engine.attach(server, options)把 engine 捕获到给定http.Server的 upgrade 请求上，适合你已经有一个http/https服务器、只想把 engine 挂到其上的场景。

这也解释了为什么示例只console.log(Server)：它验证的是“导入成功”，而真正起服务则用listen/attach二选一即可。

与仓库内其它 ESM 示例的关系

本示例专注于engine.io自身的 ESM 导入（最底层、最直接的验证）。仓库里另有一个更完整的 ESM 端到端示例 examples/es-modules，其 README 给出了npm ci→node server.js→node client.js的完整客户端/服务器跑法，可作为理解“ESM 下完整收发链路”的延伸阅读。但就“如何在 ESM 中正确import engine.io”这一具体主题，应以本示例及其背后的exports+wrapper.mjs机制为准。

小结

• engine.io产物是 CommonJS，但其 package.json 用exports的import/require双条件把 ESM 消费者导向手写的 wrapper.mjs。
• wrapper.mjs 把 CJS 构建产物的命名成员（Server、listen、attach、transports、parser、protocol等）显式转发为 ESM 命名导出，保证导入面稳定。
• 示例 index.js 配合"type": "module"（package.json），用npm link ../..+node index.js两步即可验证该导入路径可用。
• 这套“CJS 产物 + ESM 转发 shim”的组合，是同一份构建同时兼容require与import的典型工程做法。

【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io