Socket.IO 贡献指南实践：Bug 报告规范、PR 流程与 Monorepo 本地开发、编译和测试

本篇技术指南围绕 Socket.IO 仓库根目录的 CONTRIBUTING.md 展开，完整覆盖从问题分流（usage question vs. bug report）、Bug/Feature 报告规范，到 Pull Request 要求、Monorepo 包结构、本地开发环境搭建与编译/格式化/测试命令的全套贡献流程。读完后，你既能按官方标准提交高质量的 Issue 与 PR，也能在本地完整跑通 Socket.IO 各 workspace 的 TypeScript 编译、Prettier 格式检查与 Mocha 单元测试，并理解 CI 是如何验证你的改动的。

贡献前的问题分流：Issue 只收 Bug 和功能请求

CONTRIBUTING.md 的开篇即明确：issues 列表专属用于 bug 报告和功能请求。对于“怎么用”这类使用问题，官方指引的排查顺序是：

1. 阅读官方文档；
2. 查阅连接问题排查（troubleshooting-connection issues）指南；
3. 在 Stack Overflow 的 socket.io 标签下查找或提问；
4. 在社区 Discussion（Q&A 分类）中提问。

仓库的 README.md 在 "Questions" 一节重复了同样的分流口径，而仓库中 .github/ISSUE_TEMPLATE/config.yml 通过 blank_issues_enabled: false 禁用了空白 Issue，并把“Ask a Question”引导到 Discussion 分类——从配置文件可以看到，问题分流并非仅靠口头约定，而是通过 GitHub 模板机制强制执行的。

Bug 报告规范

安全漏洞走单独通道

如果你发现的是安全漏洞，CONTRIBUTING.md 明确要求不要在公开 Issue 中提交，而是参照 SECURITY.md。该文件定义了受支持版本矩阵（4.x、3.x、2.4.x 受支持，早于 2.4.0 的版本不受支持）以及通过私密渠道报告漏洞的流程。

提交前先查重

报告 Bug 前，请先在 issues 列表中检索是否已有相同报告（bug 标签），因为可能已在近期版本修复。文档特别提醒了一条容易忽略的规则：如果 Bug 在旧的、已关闭的 Issue 中被报告过但又复现了，应当开一个新 Issue，而不是在旧 Issue 下评论——这保证了维护者能通过 Issue 状态跟踪回归。

一个可受理的 Bug 报告必须包含三要素

• 相关包的版本号；
• 平台信息（设备、浏览器、操作系统）；
• 最小复现（可以 fork 官方的 socket.io-fiddle 仓库来组织示例代码）。

文档给出了底线承诺：没有清晰的复现方式，维护者无法帮助排查。仓库为此提供了标准化的模板 .github/ISSUE_TEMPLATE/bug_report.md，其结构要求填写：Bug 描述、可直接运行的 Server/Client 最小代码示例（模板内置了 import { Server } from "socket.io" 与 import { io } from "socket.io-client" 的骨架，并要求标注两侧版本号）、预期行为、设备/操作系统平台，以及附加上下文。提交后 Issue 自动打上 to triage 标签。

功能请求规范

功能请求（feature request）要求先确认 issues 列表中 enhancement 标签下是否已有相同提议，然后按 .github/ISSUE_TEMPLATE/feature_request.md 的模板填写三类信息，提交后自动打 enhancement 标签：

• 问题是什么；
• 你期望发生什么；
• 你考虑过的替代方案或替代功能。

Pull Request 指南

Bug 修复类 PR

• 若修复的是 issues 列表中已记录的 Bug，必须在 PR 描述中引用该 Issue；否则需按上文 Bug 报告规范补齐所有复现细节；
• 必须新增一个或多个测试用例，防止未来回归；
• 必须确保现有测试全部通过。

新功能类 PR

• 官方强烈建议先开功能请求并获得批准后再动手实现，并在 PR 描述中引用该请求；
• 同样要求新增测试用例、保证现有测试通过。

PR 提交时，仓库内置的 .github/PULL_REQUEST_TEMPLATE.md 会要求勾选变更类型（bug fix / new feature / 文档更新 / 性能改进 / 其他），并填写当前行为、新行为以及关联 Issue。

项目结构：基于 npm workspaces 的 Monorepo

CONTRIBUTING.md 将本仓库定性为一个 monorepo，并给出核心包职责表：

包	职责
engine.io	底层通信层的服务器端实现
engine.io-client	底层通信层的客户端实现
engine.io-parser	Engine.IO 包（packet）的编解码器，被 engine.io 与 engine.io-client 共同使用
socket.io	构建在 engine.io 之上的双向通道服务器端实现
socket.io-adapter	负责把数据包广播给所有已连接客户端的可扩展组件，被 socket.io 使用
socket.io-client	构建在 engine.io-client 之上的双向通道客户端实现
@socket.io/cluster-engine	在多个 Node.js 进程间分担负载（无需 sticky session）的集群友好引擎
@socket.io/component-emitter	跨平台 EventEmitter 实现，行为类似 Node.js 内置版本
socket.io-parser	Socket.IO 包（packet）的编解码器，被 socket.io 与 socket.io-client 共同使用

从仓库根目录 package.json 的 workspaces 字段看，当前实际登记了 12 个 workspace：除上表核心包外，还包括 socket.io-cluster-adapter、socket.io-postgres-emitter 与 socket.io-redis-streams-emitter 三个面向集群/持久化场景的扩展包。依赖层次上，各包之间通过 npm workspace 相互引用，例如 packages/socket.io/package.json 声明依赖 engine.io、socket.io-adapter、socket.io-parser——这也决定了后文编译时要“先编译依赖包，再编译目标包”的顺序。

开发环境搭建

官方要求：

• Node.js 18+；
• npm 7+——因为项目使用了 npm 的 workspaces 特性；
• 克隆仓库后执行以下命令安装全部依赖：

npm ci

官方使用的工具链为：

• TypeScript 作为开发语言；
• Rollup 做生产环境打包（见 packages/engine.io-client/support/rollup.config.umd.js 等打包配置）；
• Prettier 做代码格式化；
• Mocha 做测试；
• WebdriverIO 做浏览器与移动端测试（见 packages/socket.io-client/wdio.conf.js，本地以 Chrome 为测试浏览器，CI=true 环境下自动接入 Sauce 服务）。

常用命令：workspace 粒度的编译、格式化与测试

npm workspace 与包一一对应，命令执行粒度有两种写法：

• 作用于所有 workspace：加 --workspace 命令行参数（可缩写为 -ws）；
• 作用于指定 workspace：加 --workspace=<some-workspace> 参数。

用 TypeScript 编译

全部 workspace：

npm run compile -ws --if-present

指定 workspace（以 socket.io 为例）：

npm run compile --workspace=socket.io

--if-present 的含义是跳过未定义 compile 脚本的 workspace。各包的 compile 脚本会先清空产物目录再运行 tsc，例如 packages/socket.io/package.json 中为 rimraf ./dist && tsc；客户端包则更复杂，packages/engine.io-client/package.json 的 compile 同时执行 CJS 与 ESM 两套 tsconfig 编译（tsc && tsc -p tsconfig.esm.json）并追加 postcompile.sh 后处理，用于生成浏览器可直接加载的 build 产物。

应用格式化

全部 workspace：

npm run format:fix -ws

指定 workspace：

npm run format:fix --workspace=socket.io

各包的 format:fix 均为 prettier --write 作用于 lib/**/*.ts 与 test/** 等源码目录；配套的 format:check 只做检查不写盘，并且被织入了 test 脚本的前置环节——格式不达标会直接导致测试失败。

运行测试

全部 workspace：

npm test -ws

指定 workspace：

npm test --workspace=socket.io

以服务端核心包为例，packages/socket.io/package.json 的 test 脚本实际是一条链式流水线：

npm run format:check && npm run compile && npm run test:types && npm run test:unit

即“格式检查 → 编译 → 类型测试（tsd）→ 单元测试”依次执行。单元测试使用 nyc mocha --import=tsx --reporter spec --slow 200 --bail --timeout 10000 test/index.ts，其中 --bail 表示首个用例失败即中止，--timeout 10000 给出 10 秒的用例超时。客户端侧的 socket.io-client 测试则按环境变量分流：BROWSERS=1 时跑 WebdriverIO 浏览器测试，否则跑 Node 环境测试；engine.io-client 额外提供 test:node-fetch，用于验证基于 fetch 而非 XHR 的传输路径。

生成 Changelog

官方使用 conventional-changelog-cli 按 Angular 提交规范生成变更日志。安装后进入目标包目录运行：

npm i -g conventional-changelog-cli

cd packages/engine.io-client
conventional-changelog -p angular --tag-prefix "engine.io-client@" --commit-path .

其中 -p angular 指定按 Angular 提交约定解析提交类型，--tag-prefix 用于按该包的 git tag 前缀（如 engine.io-client@）圈定版本范围，--commit-path . 表示只统计该包目录下的提交。仓库各包目录下的 CHANGELOG.md（如 packages/engine.io-client/CHANGELOG.md）即为该流程的产物，从提交历史（chore(release): socket.io-parser@4.2.7 一类规范提交）也可印证仓库整体遵循 conventional commits 约定。

CI 如何验证你的 PR

结合 .github/workflows/ci-socket.io.yml，CI 对每个核心包配置了独立的 workflow（ci-engine.io.yml、ci-engine.io-client.yml、ci-socket.io-adapter.yml 等共 11 个），并通过 paths 过滤只在其依赖相关包变更时触发。以 socket.io 的 workflow 为例，其执行步骤与本地命令一一对应：

1. npm ci 安装依赖（对应开发环境搭建）；
2. 先编译直接依赖：engine.io-parser、engine.io、socket.io-adapter、socket.io-parser；
3. 再编译目标包：npm run compile --workspace=socket.io；
4. 编译客户端 dev 依赖 engine.io-client 与 socket.io-client（浏览器端测试需要）；
5. 最后 npm test --workspace=socket.io 跑完整测试链。

CI 使用 Node.js 24 并启用 npm 缓存（高于文档声明的 18+ 下限，文档描述的是贡献者本地的最低版本要求）。这个流程直接解释了 PR 指南中“确保现有测试仍然通过”的验收方式：你本地 npm test --workspace=<包名> 能跑通，基本等价于 CI 会通过；新增测试用例正是被这条链路（format:check → compile → test:types → test:unit）逐层验证的。

小结

CONTRIBUTING.md 定义的贡献闭环可以概括为：使用问题走文档/Stack Overflow/Discussion，Bug 与安全漏洞分渠道提交并附最小复现，新功能先获批再实现；所有 PR 附测试且保证存量测试通过。仓库侧通过 npm workspaces 管理十余个包，配合 Prettier 格式检查、TypeScript 编译、Mocha/tsx/nyc 单元测试、tsd 类型测试与 WebdriverIO 浏览器测试构成的多层验证链，以及按包切分、按路径触发的 GitHub Actions workflow，使“本地 npm ci + npm test -ws 跑绿”成为提交前最可靠的自检标准。