如何在 Node.js 中使用 y-websocket：WebSocket Polyfill 配置的 3 个关键技巧

如何在 Node.js 中使用 y-websocketWebSocket Polyfill 配置的 3 个关键技巧【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websockety-websocket 是 Yjs 官方推出的 WebSocket Provider负责在多个客户端之间实时同步协作文档与光标状态。很多新手在 Node.js 中使用 y-websocket 时都会卡在同一个问题上Node.js 环境没有浏览器内置的 WebSocket 对象直接运行就会报错。本文围绕WebSocket Polyfill 配置这一核心难点分享 3 个关键技巧帮你快速跑通 y-websocket 在 Node.js 下的完整链路。一、y-websocket 是什么能解决什么问题y-websocket 采用经典的客户端-服务器模型所有客户端连接同一个 WebSocket 端点服务端负责把文档更新document updates和意识信息awareness分发给其他客户端。它的核心能力包括✅实时文档同步基于 Yjs CRDT 算法多人同时编辑互不冲突✅光标/在线状态同步通过 awareness 协议广播用户光标、姓名等状态✅跨标签页通信同一浏览器打开同一文档时通过 BroadcastChannel降级为 localStorage直接交换变更减少服务端压力✅天然支持认证WebSocket 可以携带 header 和 cookie适合把鉴权统一放在服务端项目源码结构非常精简核心逻辑集中在src/y-websocket.js服务端启动、依赖与脚本说明可参考README.md和package.json。 提示如果你想阅读完整源码并自己改造服务端可以执行git clone https://gitcode.com/gh_mirrors/yw/y-websocket获取仓库代码。二、快速上手y-websocket 安装与启动步骤2.1 一条命令安装 y-websocketnpm i y-websocket安装时会自动带上yjs、y-protocols、lib0等依赖无需额外手动安装同步协议库。2.2 用 npx 快速启动 y-websocket 服务端HOSTlocalhost PORT1234 npx y-websocket其中PORT默认就是1234HOST默认是localhost不写环境变量也能直接运行。启动后客户端就可以通过ws://localhost:1234连接了。2.3 服务端持久化与 HTTP 回调配置默认服务端是纯内存实现重启即丢失数据。如果你需要持久化可以搭配 LevelDBHOSTlocalhost PORT1234 YPERSISTENCE./dbDir node ./node_modules/y-websocket/bin/server.cjs需要把文档变更回调给业务系统时还可以配置CALLBACK_URL、CALLBACK_DEBOUNCE_WAIT默认 2000ms 防抖等环境变量实现文档更新后自动通知后端的效果。三、关键技巧一Node.js 环境下的 WebSocket Polyfill 配置方法为什么 Node.js 需要 WebSocket Polyfilly-websocket 的客户端依赖全局WebSocket对象浏览器内置。但在 Node.js 20 及更早版本中没有原生 WebSocket直接运行会抛出WebSocket is not defined错误。解决方法是使用ws包作为 polyfill并通过WebSocketPolyfill选项注入// 先安装npm i ws const Y require(yjs) const { WebsocketProvider } require(y-websocket) const WebSocket require(ws) const doc new Y.Doc() const wsProvider new WebsocketProvider( ws://localhost:1234, my-roomname, doc, { WebSocketPolyfill: WebSocket } // 关键注入 polyfill )如果你使用 ESM 写法把require(ws)换成import WebSocket from ws即可其余配置完全一致。 小贴士Node.js 22 已经内置了全局WebSocket可以省略WebSocketPolyfill配置。不过为了兼容老版本 Node官方要求 Node 16建议仍然显式传入 polyfill。四、关键技巧二连接参数与自动重连配置WebsocketProvider的第四个参数wsOpts支持一组实用的配置项合理配置能大幅提升稳定性配置项默认值作用connecttrue是否自动连接设为false后可手动调用wsProvider.connect()params{}URL 查询参数如{ auth: token }会拼成?authtokenWebSocketPolyfill全局WebSocket注入 Node.js 环境下的 WebSocket 实现maxBackoffTime2500断线重连的最大退避等待时间毫秒采用指数退避策略awareness自动创建自定义 Awareness 实例用于共享光标等状态protocols[]指定 WebSocket 子协议resyncInterval-1每隔多少毫秒强制向服务端请求一次全量状态disableBcfalse设为true可关闭跨标签页 BroadcastChannel 通信携带 Token 进行鉴权params很适合做动态鉴权更新后会在下一次建立连接时自动生效const wsProvider new WebsocketProvider(url, room, doc, { WebSocketPolyfill: WebSocket, params: { auth: getToken() } }) // 定时刷新 token无需重建连接 wsProvider.params { auth: getNewToken() }控制连接与自动重连wsProvider.disconnect() // 主动断开且不再自动重连 wsProvider.connect() // 手动建立连接 wsProvider.destroy() // 销毁实例清理所有事件监听断线后 y-websocket 会按指数退避自动重连maxBackoffTime封顶无需自己写重连逻辑。五、关键技巧三同步状态监控与事件监听联调时最怕连上了但没同步。y-websocket 提供了一组清晰的事件方便你监控连接和同步状态事件回调参数触发时机status{ status: disconnected \| connecting \| connected }连接状态变化syncisSynced: boolean客户端收到服务端内容、完成同步connection-close关闭事件对象底层 WebSocket 连接关闭connection-error错误事件对象底层连接出错一个完整的 Node.js 客户端示例const wsProvider new WebsocketProvider(url, room, doc, { WebSocketPolyfill: WebSocket }) wsProvider.on(status, event { console.log(连接状态:, event.status) // connecting / connected / disconnected }) wsProvider.on(sync, isSynced { console.log(isSynced ? ✅ 已与服务端同步 : ⏳ 同步中...) }) wsProvider.on(connection-error, event { console.error(连接出错:, event) })用 synced 属性判断是否就绪除了事件还可以直接读取实例属性判断状态wsProvider.synced已同步、wsProvider.wsconnected已连接、wsProvider.wsconnecting连接中。例如在保存文档前检查synced可以避免保存到未同步的旧数据。六、常见问题排查清单FAQQ1报错WebSocket is not defined说明没有配置 polyfill按技巧一注入ws包或升级到 Node.js 22。Q2客户端连上了但文档内容不同步确认服务端已正常启动并且客户端与服务端连接的是同一个 roomname。y-websocket 会把 roomname 拼接到 URL 上不同房间互不可见。Q3想给多个房间分别建连接为每个房间创建独立的WebsocketProvider实例即可多个实例可以共享同一个Y.Doc。Q4连接老是断开重连检查网络或服务端稳定性可适当调大maxBackoffTime如果是鉴权过期及时更新params中的 token。总结在 Node.js 中使用 y-websocket 并不复杂关键是掌握这三个技巧配置 WebSocket Polyfill用ws包补齐 Node.js 缺失的 WebSocket 对象⚙️善用连接参数params鉴权、maxBackoffTime重连、手动connect()/disconnect()控制监控同步状态用status/sync事件和synced属性判断是否真正完成同步按照上面的步骤配置好之后你就能用 y-websocket 快速搭建出支持多人实时协作的 Node.js 应用了。动手试试吧【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考