y-websocket 参数配置完全手册8 大选项让实时协作体验拉满【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websockety-websocket 是 Yjs 生态中最常用的 WebSocket 连接器Provider它让多个客户端通过 WebSocket 实时同步文档数据与光标等在线状态。很多新手在接入 y-websocket 参数配置时只用默认值遇到鉴权、断线重连、跨标签页同步等问题就无从下手。本文从WebsocketProvider的 8 大配置选项讲起配合服务端环境变量帮你一次性掌握 y-websocket 配置的正确姿势让实时协作体验直接拉满。y-websocket 是什么先认识这个实时协作的传输层在深入 y-websocket 参数配置之前先明确它的定位它采用经典的客户端-服务器模型。所有客户端连接到同一个 WebSocket 端点由服务器负责把文档更新update和在线状态awareness比如共享光标分发给房间内的其他客户端。它的核心优势在于✅集中式鉴权WebSocket 能携带 Cookie 和请求头可直接复用你现有的登录体系✅跨标签页通信同一浏览器打开同一文档时通过 BroadcastChannel 直接同步不重复走服务器✅在线状态同步天然支持共享光标、用户列表等协作体验服务端自带一个简单的内存版后端想要快速跑起来只需一条命令HOSTlocalhost PORT1234 npx y-websocket完整的官方说明见 README.md服务端源码在 bin/server.cjs。y-websocket 快速上手一分钟跑通客户端客户端使用非常简单只需三步创建Y.Doc、创建WebsocketProvider、监听状态事件。import * as Y from yjs import { WebsocketProvider } from y-websocket const doc new Y.Doc() const wsProvider new WebsocketProvider(ws://localhost:1234, my-roomname, doc) wsProvider.on(status, event { console.log(event.status) // connected 或 disconnected })构造函数签名如下定义见 src/y-websocket.jsnew WebsocketProvider(serverUrl, roomname, doc, wsOpts)真正的参数配置核心就在第四个参数wsOpts里下面逐一拆解这 8 大选项。一张表看懂 8 大客户端配置选项选项默认值作用connecttrue创建实例后是否自动连接params{}附加到 URL 的查询参数常用于鉴权protocols[]WebSocket 子协议列表WebSocketPolyfill浏览器原生WebSocketNode.js 环境替换实现awareness自动创建复用已有的在线状态实例resyncInterval-1定时向服务端请求全量状态毫秒maxBackoffTime2500断线重连的最大等待时间毫秒disableBcfalse是否禁用跨标签页 BroadcastChannel 通信8 大选项逐个拆解y-websocket 参数配置详解1.connect手动控制 y-websocket 连接时机默认true表示实例一创建就自动发起连接。如果你的场景需要登录成功后再连或页面可见时才连可以关掉自动连接再手动调用connect()/disconnect()控制const provider new WebsocketProvider(url, room, doc, { connect: false }) // 合适的时机再连接 provider.connect() // 需要断开且不重连时 provider.disconnect()2.paramsy-websocket 鉴权参数配置的最佳姿势这是最常用也最实用的选项。params中的键值对会被 url-encoded 后拼到连接地址上例如{ auth: bearer }会变成?authbearer。服务端在upgrade事件中即可读取校验。更重要的是params可以随时安全地更新——新值会在下一次建立连接时生效。如果你的 token 会过期可以周期性刷新它无需重建实例const provider new WebsocketProvider(url, room, doc, { params: { token: getToken() } }) // token 刷新后直接更新下次重连自动携带新值 provider.params { token: getNewToken() } 提示携带敏感 token 时建议配合服务端 HTTPS/WSS 使用避免明文传输。3.protocolsWebSocket 子协议协商对应原生 WebSocket 构造函数的protocols参数用于在握手阶段与服务端协商子协议。大多数场景用不到需要自定义协议如json、mqtt时可传入字符串数组const provider new WebsocketProvider(url, room, doc, { protocols: [my-protocol] })4.WebSocketPolyfilly-websocket 在 Node.js 环境的配置浏览器自带WebSocket但 Node.js 没有。官方推荐的方案是用ws包做 polyfillconst provider new WebsocketProvider(url, room, doc, { WebSocketPolyfill: require(ws) })这样你的 y-websocket 客户端就能在服务端、CLI 工具等 Node.js 环境稳定运行。5.awareness复用并定制在线状态默认情况下 provider 会基于doc自动创建Awareness实例。如果你已经有一个实例例如多个 provider 共享同一份在线状态可以显式传入import * as awarenessProtocol from y-protocols/awareness const awareness new awarenessProtocol.Awareness(doc) const provider new WebsocketProvider(url, room, doc, { awareness })共享光标、在线用户列表等感知层功能都依赖它值得单独研究。6.resyncInterval定时重新同步保障一致性默认-1表示不启用。如果客户端长期在线且希望定期与服务器校准状态比如防止长时间运行后数据偏差可以设置一个毫秒间隔。设置后provider 会定时重发同步请求// 每 30 秒请求一次服务端状态 const provider new WebsocketProvider(url, room, doc, { resyncInterval: 30000 })⚠️ 注意频繁同步会增加网络开销建议仅在确有需要时开启。7.maxBackoffTime优化 y-websocket 断线重连体验网络抖动时y-websocket 会采用指数退避策略自动重连从 100ms 起步每次失败翻倍直到达到maxBackoffTime上限默认 2500ms。把这个值调大可以减少服务器压力、避免重连风暴调小则恢复更快// 最多每 5 秒重试一次 const provider new WebsocketProvider(url, room, doc, { maxBackoffTime: 5000 })8.disableBc关闭跨标签页广播通道默认开启的 BroadcastChannel 能让同一浏览器内多个标签页直接互通无需经过服务器实时性更好。但如果你不希望标签页之间共享数据例如每个标签页独立账号可以显式关闭const provider new WebsocketProvider(url, room, doc, { disableBc: true })别忘了服务端y-websocket 服务端环境变量配置客户端配置到位后服务端同样可以通过环境变量精细调优环境变量默认值作用HOSTlocalhost监听地址PORT1234监听端口YPERSISTENCE不启用设置后启用 LevelDB 持久化GC开启设为false可关闭文档垃圾回收CALLBACK_URL不启用文档更新时回调的 HTTP 地址CALLBACK_DEBOUNCE_WAIT2000回调防抖等待时间毫秒CALLBACK_DEBOUNCE_MAXWAIT10000回调最大等待时间毫秒CALLBACK_TIMEOUT5000HTTP 回调超时毫秒CALLBACK_OBJECTS{}需要回调的共享对象及类型 JSON一个带持久化和回调的完整启动示例HOSTlocalhost PORT1234 YPERSISTENCE./dbDir \ CALLBACK_URLhttp://localhost:3000/ \ CALLBACK_OBJECTS{prosemirror:XmlFragment} \ node ./node_modules/y-websocket/bin/server.cjs相关实现可参考 bin/utils.cjs 与 bin/callback.cjs。实战清单让 y-websocket 实时协作体验拉满上线必配用params携带鉴权 token并定时刷新安全与体验兼得重连策略按业务容忍度调整maxBackoffTime避免重连风暴️Node.js 场景记得配置WebSocketPolyfill️多标签页保持默认的 BroadcastChannel享受秒级本地同步️数据持久化服务端设置YPERSISTENCE刷新页面不丢内容回调集成用CALLBACK_*系列把文档变更推送给自己的后端总结y-websocket 参数配置并不复杂8 大选项各有明确职责connect管时机、params管鉴权、resyncInterval与maxBackoffTime管同步与重连、WebSocketPolyfill管运行环境、awareness与disableBc管协作与通信方式。配合服务端环境变量你就能构建出既稳定又流畅的实时协作应用。希望这份 y-websocket 参数配置完全手册能帮你少踩坑快速上手【免费下载链接】y-websocketWebsocket Connector for Yjs项目地址: https://gitcode.com/gh_mirrors/yw/y-websocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考