y-websocket Awareness 协议实战30 分钟实现多人光标与在线状态【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket如果你正在开发协同编辑、在线白板或多人表格这类应用一定绕不开「实时感知对方状态」这个需求光标在哪、谁在线、谁正在输入。y-websocket 是 Yjs 官方推出的 WebSocket 连接器而它内置的Awareness 协议正是解决这类问题的标准方案。本文将通过 30 分钟实战带你从零实现多人光标同步与在线状态管理全程只讲最核心的用法代码量极少新手也能轻松跟上。y-websocket 与 Awareness 协议是什么一个连接器 一套感知协议y-websocket 在 Yjs 生态中扮演「运输官」的角色它建立客户端与服务器之间的 WebSocket 长连接负责分发文档更新写入共享数据和Awareness 信息非持久化的实时状态。两者最大的区别在于维度文档数据DocAwareness 状态是否持久化是会写入底层存储否断线即消失典型内容文本、字段、结构化数据光标位置、在线状态、当前选中是否需要 CRDT 合并需要不需要后到覆盖先到生命周期长期存在随连接建立/断开简单说Awareness 协议管的是「人」文档协议管的是「数据」。像 Notion、Google Docs 里的协作者头像列表、彩色光标背后就是 Awareness 在发力。核心 APIlocalState 与 getStates在 y-websocket 中每个客户端通过provider.awareness暴露两个关键入口setLocalState()发布自己当前的状态如光标坐标、用户名、颜色getStates()读取所有在线协作者的状态集合状态用clientID作为键服务端只负责转发不做合并这就是它轻量高效的秘密。30 分钟实战完整实现多人光标与在线状态下面按步骤拆解每一步都给出可直接运行的代码跟着做即可。第一步安装依赖约 5 分钟y-websocket 以 npm 包形式发布安装一条命令搞定npm i y-websocket如果你希望直接查看源码并本地调试也可以克隆仓库git clone https://gitcode.com/gh_mirrors/yw/y-websocket cd y-websocket npm install第二步启动 y-websocket 服务端约 5 分钟仓库内置了一个开箱即用的内存版服务器一条命令即可启动HOSTlocalhost PORT1234 npx y-websocket服务端逻辑集中在bin/目录本镜像中主要实现位于 src/y-websocket.js它会自动处理连接、消息分发与断线清理你无需关心内部细节。第三步客户端接入 WebSocket约 10 分钟创建一个 Yjs 文档并把它接入 WebSocket 房间import * as Y from yjs import { WebsocketProvider } from y-websocket const doc new Y.Doc() const provider new WebsocketProvider(ws://localhost:1234, my-room, doc) provider.on(status, event { console.log(连接状态, event.status) // connected / connecting / disconnected })核心就是WebsocketProvider类定义于 src/y-websocket.js它内部自动维护了重连、心跳检测和状态广播。第四步发布自己的光标与在线状态约 5 分钟连接建立后把用户信息和光标坐标写进本地 Awareness 状态即可provider.awareness.setLocalState({ user: { name: 小明, color: #ff5722 }, cursor: { x: 120, y: 340 } })这一行代码触发的事件会被服务端实时转发给房间里所有其他客户端。你还可以在鼠标移动时持续更新坐标实现丝滑的光标跟随。第五步监听并渲染其他协作者约 5 分钟订阅 Awareness 的change事件就能拿到增删改的用户列表provider.awareness.on(change, ({ added, updated, removed }) { const states provider.awareness.getStates() for (const id of added.concat(updated)) { const s states.get(id) if (s?.user) { console.log(${s.user.name} 的光标在 (${s.cursor.x}, ${s.cursor.y})) } } for (const id of removed) { console.log(用户 ${id} 已离线) } })到这里多人光标同步和在线状态已经完整跑通总耗时不超过 30 分钟 。渲染部分只需要把坐标画成带有用户名的小标签即可。深入Awareness 协议的消息机制如果你好奇背后是如何通信的可以看 src/y-websocket.js 中定义的四种消息类型消息常量值用途messageSync0同步 Yjs 文档数据messageAwareness1广播/应用 Awareness 状态更新messageAuth2服务端权限校验messageQueryAwareness3新客户端请求全量状态两个关键处理函数收到状态更新messageHandlers[messageAwareness]src/y-websocket.js调用applyAwarenessUpdate把远端状态合并进本地。本地状态变化_awarenessUpdateHandlersrc/y-websocket.js监听到setLocalState后立即把变更编码并广播出去。新连接如何拿到「存量状态」新客户端加入时会发送messageQueryAwareness见 src/y-websocket.js服务端收到后把当前所有在线用户的状态一次性回传。这也是为什么你打开页面就能立刻看到已有的协作者而不是等对方再次移动光标。在线状态与离线检测机制Awareness 协议的贴心之处在于自动过期清理每个状态都带时间戳客户端定期刷新默认 15 秒服务端和客户端都会在超时后将其标记为离线。此外断线重连时连接关闭逻辑会调用removeAwarenessStatessrc/y-websocket.js清理所有远端状态避免「幽灵光标」残留。浏览器多个标签页打开同一文档时y-websocket 会通过 BroadcastChannel 就近同步见 src/y-websocket.js无需绕行服务器体验更快。所以「谁在线」这件事你完全不需要自己维护Awareness 协议已经帮你处理好了离线、刷新、断线等所有边界情况。常见问题与避坑指南问题原因与解决办法光标偶尔「卡住不动」状态更新频率过高导致。用节流如每 50ms 只发一次控制setLocalState调用用户下线后状态未消失等待超时自动清理即可如想立即清理可手动调用awareness.removeAwarenessStates()Node.js 环境无法连接浏览器端 WebSocket 在 Node 中不存在需要传入WebSocketPolyfill: require(ws)想带认证信息通过params选项附加 token例如new WebsocketProvider(url, room, doc, { params: { auth: token } })总结y-websocket 的Awareness 协议把「实时感知用户状态」这个复杂问题压缩成了两行 API一个发布、一个订阅。通过本文的 30 分钟实战你已经掌握了多人光标同步、在线状态展示、离线检测三大核心能力。下一步你可以在其之上叠加自己的业务状态——比如「正在输入」「当前选中段落」甚至「视频通话中的鼠标轨迹」原理完全一致。关键文件速查消息类型与处理器src/y-websocket.jsAwareness 广播逻辑src/y-websocket.js连接与重连管理src/y-websocket.js【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考