socket.io-client 发布流程详解从版本号管理到 npm 可信发布与 CDN 分发【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io本文以 socket.io 官方仓库中的发布说明文档packages/socket.io-client/RELEASING.md为主线逐步骤拆解 socket.io-client 客户端包的完整发布流程双 package.json 版本号管理、Changelog 生成、TypeScript 编译与 Rollup 打包、Git tag 触发以及基于 npm Trusted Publishing 的自动化发布和 CDN 产物同步。读完后你将理解一个真实生产级 monorepo 中客户端库从改版本号到用户可在 npm / CDN 上使用的全链路机制并能对照源码验证每一步的实际实现。发布流程总览九步走官方文档 RELEASING.md 给出的完整发布步骤为更新package.json中的版本号更新support/package.esm.json中的版本号执行conventional-changelog -p angular更新CHANGELOG.md执行npm run compile编译 TypeScript 源码执行npm run build生成浏览器用的 bundle提交package.json、support/package.esm.json、CHANGELOG.md和dist/目录的变更创建形如socket.io-clientx.y.z的 tag 并推送由 CI 工作流 .github/workflows/publish.yml 通过 Trusted Publishing 安全地把包发布到 npm创建一个 GitHub Release把 bundle 拷贝到官方 CDN 仓库使其可以在cdn.socket.io/域名下被直接引用。下面结合仓库中的真实文件逐步展开每个环节的实现细节。为什么要维护两个版本号package.json与support/package.esm.json第一步和第二步看似重复实则服务于不同产物。当前 packages/socket.io-client/package.json 的版本为4.8.3而 support/package.esm.json 内容极简{ name: socket.io-client, version: 4.8.3, type: module }原因在于主package.json声明了type: commonjs第 17 行这决定了 Node.js 把包内.js文件按 CJS 解析。而客户端同时需要发布 ESM 产物——exports字段显示import条件下default指向./build/esm/index.jsrequire条件下指向./build/cjs/index.js两者各自携带独立的.d.ts类型声明。若build/esm/目录下的.js仍落在一个type: commonjs的包根之下ESM 语义就会被破坏。postcompile.sh 脚本第 3 行给出了答案cp ./support/package.esm.json ./build/esm/package.json即在编译后向build/esm/package.json复制一份带type: module标记的子包描述文件让 ESM 产物被 Node 正确识别。因此两个文件中的版本号必须保持一致——它们最终都出现在发布物中前者是 npm 包元信息后者是 ESM 产物的模块标记这正是文档把它们列为两个独立步骤、并要求在步骤 6 中一并提交的原因。用 Conventional Changelog 生成变更日志第三步要求用conventional-changelog -p angular更新 CHANGELOG.md。当前文件呈现出该工具生成的典型格式顶部是一张版本汇总表列为版本 / 发布日期 / UMD 压缩包大小mingzip例如最新的4.8.3对应14.4 KB每个版本一节包含按 angular 提交类型归类的Bug Fixes、Features、Dependencies等分组并附带 commit 短哈希与 issue 链接如 4.8.2 版本中的* **bundle** do not mangle the _placeholder attribute (bis) * drain queue before emitting connect采用 angular 预设意味着维护者的 commit message 遵循 Conventional Commits 规范fix:、feat:、chore:等前缀加 scope变更日志才能被自动聚合。这对用户也有实际价值Changelog 直接记录了依赖变更如engine.io-client~6.6.1、ws~8.18.3帮助应用方判断是否需要升级。编译阶段npm run compile到底做了什么第四步的npm run compile对应 package.json 中的脚本定义compile: rimraf ./build tsc tsc -p tsconfig.esm.json ./postcompile.sh它依次做四件事rimraf ./build清理旧产物保证可重现构建tsc按 tsconfig.json 将lib/编译为 CommonJSoutDir为build/cjs/target为es2018注释注明对应 Node.js 10与包声明的engines: { node: 10.0.0 }一致declaration: true会产出.d.tstsc -p tsconfig.esm.json按 tsconfig.esm.json 再以module: esnext编译一遍到build/esm/./postcompile.sh做三项后处理。postcompile.sh 的完整逻辑值得逐行看cp ./support/package.esm.json ./build/esm/package.json cp -r ./build/esm/ ./build/esm-debug/ if [[ $OSTYPE darwin* ]]; then sed -i -e /debug(/d ./build/esm/*.js else sed -i -e /debug(/d ./build/esm/*.js fi # for backward compatibility with const socket require(socket.io-client)(...) echo -e \nmodule.exports lookup; ./build/cjs/index.js复制 ESM 标记文件即前述的build/esm/package.json派生出build/esm-debug/从build/esm/整目录复制一份之后再从build/esm/*.js中用sed删除所有debug(调用行。于是build/esm/成为剥离了debug包依赖的精简版浏览器入口走这条路径而build/esm-debug/保留了调试日志。这一设计直接反映在主package.json的exports中importnode条件指向./build/esm-debug/index.js浏览器default指向./build/esm/index.jsCJS 尾部追加module.exports lookup;脚本中的注释写明这是为了向后兼容const socket require(socket.io-client)(...)这种直接调用默认导出的旧写法。值得注意的是prepack脚本prepack: npm run compile。即使发布流程由 CI 执行npm pack/publish前也会自动重新编译一次构成一道安全网。构建浏览器 Bundlenpm run build的三路输出第五步npm run build执行三条 Rollup 命令见 package.json 第 59 行build: rollup -c support/rollup.config.umd.js rollup -c support/rollup.config.esm.js rollup -c support/rollup.config.umd.msgpack.jsUMD 双产物开发版 压缩版support/rollup.config.umd.js 导出两个配置对象分别产出产物输入后处理dist/socket.io.jsbuild/esm-debug/browser-entrypoint.js保留 debugBabelbabel/preset-env object-assign / classes 转换带 sourcemapdist/socket.io.min.jsbuild/esm/browser-entrypoint.js已去 debug额外经 Terser 压缩mangle 时按正则/^_/处理属性名并保留_placeholder两者都以umd格式输出、全局名为io因此页面上可用io(url)创建连接文件头带有 banner/*! * Socket.IO v4.8.3 * (c) 2014-2026 Guillermo Rauch * Released under the MIT License. */其中版本号直接取自package.json配置第 6 行require(../package.json).version——再次印证了发布前必须先改版本号否则 bundle banner 也会带错版本。reserved: [_placeholder]这个细节并非偶然CHANGELOG 4.8.2 条目专门记录了一次 do not mangle the _placeholder attribute (bis) 的修复说明压缩保留规则是踩过坑后写死的。ESM 压缩产物support/rollup.config.esm.js 从build/esm/index.js打包出dist/socket.io.esm.min.jsformat: esm Terser供现代打包器直接消费 ESM 版本。MsgPack 变体support/rollup.config.umd.msgpack.js 复用 UMD 压缩配置的 output仅改输出文件名并用rollup/plugin-alias做一次关键替换alias({ entries: [ { find: socket.io-parser, replacement: socket.io-msgpack-parser, }, ], })即把标准 JSON 解析器socket.io-parser在打包时静态替换为 MsgPack 解析器产出dist/socket.io.msgpack.min.js为需要二进制紧凑传输的用户提供免配置的 MsgPack 客户端。发布物范围主package.json的files字段为[dist/, build/]说明 npm 包最终同时携带 Node 产物build/cjs、build/esm、build/esm-debug与浏览器 bundledist/这也解释了为什么文档第 6 步要求把dist/目录一并提交进仓库——bundle 是预先构建好入库的tag 触发发布时 CI 只需重新编译校验即可。提交与打 tag触发自动发布的钥匙完成前六步并提交后第 7 步是创建 tagsocket.io-clientx.y.z并推送。这里的packageversion格式不是约定俗成而是发布工作流的硬契约.github/workflows/publish.yml 的触发条件为on: push: tags: # expected format: packageversion (example: socket.io1.2.3) - ***工作流的权限声明是关键permissions: contents: read id-token: write文件开头的注释点明其依赖的两大 npm 机制trusted publishing可信发布凭 GitHub 工作流身份签发 OIDC token 换取 npm 发布权与staged publishing暂存发布新注册包名的自动审核期。因此整个仓库不需要也不存储任何 NPM_TOKEN安全性高于传统的塞一个 npm 密钥进 secret模式。工作流的执行步骤依次是actions/checkoutv6检出代码actions/setup-nodev6安装 Node.js 26 并指向registry.npmjs.org注意 ci-socket.io-client.yml 中日常 CI 用 Node.js 24发布用 26npm ci按 lockfile 精确安装依赖npm run compile --workspaces --if-present编译全部工作区——因为 package.json 根部的workspaces列出了socket.io-client及其依赖链engine.io-parser、engine.io-client、socket.io-parser等最终执行npm stage publish --workspace${GITHUB_REF_NAME%*} --access public${GITHUB_REF_NAME%*}是 Bash 参数展开去掉 tag 名中第一个及其之后的部分tagsocket.io-client4.8.4→ workspace 名socket.io-client再配合npm stage publish完成带暂存发布语义的正式 publish。也就是说tag 名本身编码了发哪个包、发什么版本的全部信息这是把多包 monorepo 的发布编排压缩到一条 shell 命令里的巧妙设计。收尾两步GitHub Release 与 CDN 同步第 8 步是在官方 GitHub 仓库创建一个 Release附上该版本的变更摘要——这也是 CHANGELOG.md 中各版本锚点如#483-2025-12-23对应的用户可见入口。第 9 步则面向script src直连场景把dist/下的 bundle 同步到独立的官方 CDN 仓库使用户可以直接引用形如https://cdn.socket.io/4.8.3/socket.io.min.js的地址无需经过 npm。这一步是纯文件分发与 npm 发布相互独立——即使 npm 侧包处于 staged 审核期CDN 产物依然可用。对照 CI 理解本地验证发布前置条件隐含在 CI 中ci-socket.io-client.yml 展示了改动packages/socket.io-client/**等路径时触发的验证链——先依次编译上游依赖engine.io-parser、engine.io-client、socket.io-parser再编译本包然后跑npm test默认 Node 端 mocha 用例test:node脚本使用tsx直接加载test/index.tspush 事件下还会以BROWSERS1追加浏览器端测试。发布者在本地执行步骤 4、5 前跑通npm test等价于提前复现了 CI 的编译链路。小结socket.io-client 的发布流程可以用一条数据流概括改版本号package.json support/package.esm.json → conventional-changelog -p angular 更新 CHANGELOG.md → npm run compilerimraf 双 tsc postcompile.shesm 标记 / esm-debug / 去 debug / cjs 兼容 → npm run buildUMD 双产物 ESM min MsgPack 变体 → 提交元信息与 dist/ → push tag socket.io-clientx.y.z → publish.ymlNode 26 npm ci 全工作区编译 npm stage publish可信发布无 token → GitHub Release CDN 仓库同步其工程要点值得借鉴版本号在元信息与构建产物中多处出现靠脚本而非人工保证一致性banner、esm 子包均由版本号派生发布凭证零落库OIDC 可信发布tag 命名即发布指令packageversion被 shell 展开直接解析出 workspacenpm 包与浏览器 bundle 双通道分发build/面向 Nodedist/面向打包器与 CDN。以上全部细节均可在仓库的 packages/socket.io-client 目录及 .github/workflows 中逐一对照验证。【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
socket.io-client 发布流程详解：从版本号管理到 npm 可信发布与 CDN 分发
socket.io-client 发布流程详解从版本号管理到 npm 可信发布与 CDN 分发【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io本文以 socket.io 官方仓库中的发布说明文档packages/socket.io-client/RELEASING.md为主线逐步骤拆解 socket.io-client 客户端包的完整发布流程双 package.json 版本号管理、Changelog 生成、TypeScript 编译与 Rollup 打包、Git tag 触发以及基于 npm Trusted Publishing 的自动化发布和 CDN 产物同步。读完后你将理解一个真实生产级 monorepo 中客户端库从改版本号到用户可在 npm / CDN 上使用的全链路机制并能对照源码验证每一步的实际实现。发布流程总览九步走官方文档 RELEASING.md 给出的完整发布步骤为更新package.json中的版本号更新support/package.esm.json中的版本号执行conventional-changelog -p angular更新CHANGELOG.md执行npm run compile编译 TypeScript 源码执行npm run build生成浏览器用的 bundle提交package.json、support/package.esm.json、CHANGELOG.md和dist/目录的变更创建形如socket.io-clientx.y.z的 tag 并推送由 CI 工作流 .github/workflows/publish.yml 通过 Trusted Publishing 安全地把包发布到 npm创建一个 GitHub Release把 bundle 拷贝到官方 CDN 仓库使其可以在cdn.socket.io/域名下被直接引用。下面结合仓库中的真实文件逐步展开每个环节的实现细节。为什么要维护两个版本号package.json与support/package.esm.json第一步和第二步看似重复实则服务于不同产物。当前 packages/socket.io-client/package.json 的版本为4.8.3而 support/package.esm.json 内容极简{ name: socket.io-client, version: 4.8.3, type: module }原因在于主package.json声明了type: commonjs第 17 行这决定了 Node.js 把包内.js文件按 CJS 解析。而客户端同时需要发布 ESM 产物——exports字段显示import条件下default指向./build/esm/index.jsrequire条件下指向./build/cjs/index.js两者各自携带独立的.d.ts类型声明。若build/esm/目录下的.js仍落在一个type: commonjs的包根之下ESM 语义就会被破坏。postcompile.sh 脚本第 3 行给出了答案cp ./support/package.esm.json ./build/esm/package.json即在编译后向build/esm/package.json复制一份带type: module标记的子包描述文件让 ESM 产物被 Node 正确识别。因此两个文件中的版本号必须保持一致——它们最终都出现在发布物中前者是 npm 包元信息后者是 ESM 产物的模块标记这正是文档把它们列为两个独立步骤、并要求在步骤 6 中一并提交的原因。用 Conventional Changelog 生成变更日志第三步要求用conventional-changelog -p angular更新 CHANGELOG.md。当前文件呈现出该工具生成的典型格式顶部是一张版本汇总表列为版本 / 发布日期 / UMD 压缩包大小mingzip例如最新的4.8.3对应14.4 KB每个版本一节包含按 angular 提交类型归类的Bug Fixes、Features、Dependencies等分组并附带 commit 短哈希与 issue 链接如 4.8.2 版本中的* **bundle** do not mangle the _placeholder attribute (bis) * drain queue before emitting connect采用 angular 预设意味着维护者的 commit message 遵循 Conventional Commits 规范fix:、feat:、chore:等前缀加 scope变更日志才能被自动聚合。这对用户也有实际价值Changelog 直接记录了依赖变更如engine.io-client~6.6.1、ws~8.18.3帮助应用方判断是否需要升级。编译阶段npm run compile到底做了什么第四步的npm run compile对应 package.json 中的脚本定义compile: rimraf ./build tsc tsc -p tsconfig.esm.json ./postcompile.sh它依次做四件事rimraf ./build清理旧产物保证可重现构建tsc按 tsconfig.json 将lib/编译为 CommonJSoutDir为build/cjs/target为es2018注释注明对应 Node.js 10与包声明的engines: { node: 10.0.0 }一致declaration: true会产出.d.tstsc -p tsconfig.esm.json按 tsconfig.esm.json 再以module: esnext编译一遍到build/esm/./postcompile.sh做三项后处理。postcompile.sh 的完整逻辑值得逐行看cp ./support/package.esm.json ./build/esm/package.json cp -r ./build/esm/ ./build/esm-debug/ if [[ $OSTYPE darwin* ]]; then sed -i -e /debug(/d ./build/esm/*.js else sed -i -e /debug(/d ./build/esm/*.js fi # for backward compatibility with const socket require(socket.io-client)(...) echo -e \nmodule.exports lookup; ./build/cjs/index.js复制 ESM 标记文件即前述的build/esm/package.json派生出build/esm-debug/从build/esm/整目录复制一份之后再从build/esm/*.js中用sed删除所有debug(调用行。于是build/esm/成为剥离了debug包依赖的精简版浏览器入口走这条路径而build/esm-debug/保留了调试日志。这一设计直接反映在主package.json的exports中importnode条件指向./build/esm-debug/index.js浏览器default指向./build/esm/index.jsCJS 尾部追加module.exports lookup;脚本中的注释写明这是为了向后兼容const socket require(socket.io-client)(...)这种直接调用默认导出的旧写法。值得注意的是prepack脚本prepack: npm run compile。即使发布流程由 CI 执行npm pack/publish前也会自动重新编译一次构成一道安全网。构建浏览器 Bundlenpm run build的三路输出第五步npm run build执行三条 Rollup 命令见 package.json 第 59 行build: rollup -c support/rollup.config.umd.js rollup -c support/rollup.config.esm.js rollup -c support/rollup.config.umd.msgpack.jsUMD 双产物开发版 压缩版support/rollup.config.umd.js 导出两个配置对象分别产出产物输入后处理dist/socket.io.jsbuild/esm-debug/browser-entrypoint.js保留 debugBabelbabel/preset-env object-assign / classes 转换带 sourcemapdist/socket.io.min.jsbuild/esm/browser-entrypoint.js已去 debug额外经 Terser 压缩mangle 时按正则/^_/处理属性名并保留_placeholder两者都以umd格式输出、全局名为io因此页面上可用io(url)创建连接文件头带有 banner/*! * Socket.IO v4.8.3 * (c) 2014-2026 Guillermo Rauch * Released under the MIT License. */其中版本号直接取自package.json配置第 6 行require(../package.json).version——再次印证了发布前必须先改版本号否则 bundle banner 也会带错版本。reserved: [_placeholder]这个细节并非偶然CHANGELOG 4.8.2 条目专门记录了一次 do not mangle the _placeholder attribute (bis) 的修复说明压缩保留规则是踩过坑后写死的。ESM 压缩产物support/rollup.config.esm.js 从build/esm/index.js打包出dist/socket.io.esm.min.jsformat: esm Terser供现代打包器直接消费 ESM 版本。MsgPack 变体support/rollup.config.umd.msgpack.js 复用 UMD 压缩配置的 output仅改输出文件名并用rollup/plugin-alias做一次关键替换alias({ entries: [ { find: socket.io-parser, replacement: socket.io-msgpack-parser, }, ], })即把标准 JSON 解析器socket.io-parser在打包时静态替换为 MsgPack 解析器产出dist/socket.io.msgpack.min.js为需要二进制紧凑传输的用户提供免配置的 MsgPack 客户端。发布物范围主package.json的files字段为[dist/, build/]说明 npm 包最终同时携带 Node 产物build/cjs、build/esm、build/esm-debug与浏览器 bundledist/这也解释了为什么文档第 6 步要求把dist/目录一并提交进仓库——bundle 是预先构建好入库的tag 触发发布时 CI 只需重新编译校验即可。提交与打 tag触发自动发布的钥匙完成前六步并提交后第 7 步是创建 tagsocket.io-clientx.y.z并推送。这里的packageversion格式不是约定俗成而是发布工作流的硬契约.github/workflows/publish.yml 的触发条件为on: push: tags: # expected format: packageversion (example: socket.io1.2.3) - ***工作流的权限声明是关键permissions: contents: read id-token: write文件开头的注释点明其依赖的两大 npm 机制trusted publishing可信发布凭 GitHub 工作流身份签发 OIDC token 换取 npm 发布权与staged publishing暂存发布新注册包名的自动审核期。因此整个仓库不需要也不存储任何 NPM_TOKEN安全性高于传统的塞一个 npm 密钥进 secret模式。工作流的执行步骤依次是actions/checkoutv6检出代码actions/setup-nodev6安装 Node.js 26 并指向registry.npmjs.org注意 ci-socket.io-client.yml 中日常 CI 用 Node.js 24发布用 26npm ci按 lockfile 精确安装依赖npm run compile --workspaces --if-present编译全部工作区——因为 package.json 根部的workspaces列出了socket.io-client及其依赖链engine.io-parser、engine.io-client、socket.io-parser等最终执行npm stage publish --workspace${GITHUB_REF_NAME%*} --access public${GITHUB_REF_NAME%*}是 Bash 参数展开去掉 tag 名中第一个及其之后的部分tagsocket.io-client4.8.4→ workspace 名socket.io-client再配合npm stage publish完成带暂存发布语义的正式 publish。也就是说tag 名本身编码了发哪个包、发什么版本的全部信息这是把多包 monorepo 的发布编排压缩到一条 shell 命令里的巧妙设计。收尾两步GitHub Release 与 CDN 同步第 8 步是在官方 GitHub 仓库创建一个 Release附上该版本的变更摘要——这也是 CHANGELOG.md 中各版本锚点如#483-2025-12-23对应的用户可见入口。第 9 步则面向script src直连场景把dist/下的 bundle 同步到独立的官方 CDN 仓库使用户可以直接引用形如https://cdn.socket.io/4.8.3/socket.io.min.js的地址无需经过 npm。这一步是纯文件分发与 npm 发布相互独立——即使 npm 侧包处于 staged 审核期CDN 产物依然可用。对照 CI 理解本地验证发布前置条件隐含在 CI 中ci-socket.io-client.yml 展示了改动packages/socket.io-client/**等路径时触发的验证链——先依次编译上游依赖engine.io-parser、engine.io-client、socket.io-parser再编译本包然后跑npm test默认 Node 端 mocha 用例test:node脚本使用tsx直接加载test/index.tspush 事件下还会以BROWSERS1追加浏览器端测试。发布者在本地执行步骤 4、5 前跑通npm test等价于提前复现了 CI 的编译链路。小结socket.io-client 的发布流程可以用一条数据流概括改版本号package.json support/package.esm.json → conventional-changelog -p angular 更新 CHANGELOG.md → npm run compilerimraf 双 tsc postcompile.shesm 标记 / esm-debug / 去 debug / cjs 兼容 → npm run buildUMD 双产物 ESM min MsgPack 变体 → 提交元信息与 dist/ → push tag socket.io-clientx.y.z → publish.ymlNode 26 npm ci 全工作区编译 npm stage publish可信发布无 token → GitHub Release CDN 仓库同步其工程要点值得借鉴版本号在元信息与构建产物中多处出现靠脚本而非人工保证一致性banner、esm 子包均由版本号派生发布凭证零落库OIDC 可信发布tag 命名即发布指令packageversion被 shell 展开直接解析出 workspacenpm 包与浏览器 bundle 双通道分发build/面向 Nodedist/面向打包器与 CDN。以上全部细节均可在仓库的 packages/socket.io-client 目录及 .github/workflows 中逐一对照验证。【免费下载链接】socket.ioBidirectional and low-latency communication for every platform项目地址: https://gitcode.com/gh_mirrors/so/socket.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考