在线协作 Presence 实战：从光标同步到协作体温

在线协作工具的体验，拆到最后往往只剩下两个词：快，和，在场。快解决的是效率问题，在场解决的是信任问题。Presence 插件在我们项目里承担的就是后者——让每个人能看见"谁在旁边、正在做什么、光标停在哪一行"。这篇文章是体验篇，我不打算只贴一份配置文档，而是把 Presence 从"能力地图"讲到"踩坑实录"，再到"感知设计"，完整记录我们是怎么把一个原本冷冰冰的编辑器，做成有温度、能感受到队友呼吸节奏的协作空间。如果你正在做协同类产品，或者打算给自己的应用加入在线协作能力，这篇应该能帮你少走几段弯路。

1. 为什么在线协作工具总觉得"隔着屏幕"

远程办公最反直觉的一点，是工具越发达，孤独感越强。文档能同时编辑，评论能实时回复，视频会议能随时开——但你在光标停留的地方，感受不到对面那个人也正盯着同一块屏幕。这种"看不见彼此"的体验断层，恰恰是 Presence 概念被单独拎出来的原因。

Presence 的核心价值，不是传输数据，而是重建"位置感"。通俗说，就是让远端用户的存在变得可见、可信、可预期。打个比方：微信群里的"正在输入"四个字，比消息本身更能传递"ta 在认真回复你"的情绪信号。Presence 就是把这种信号从聊天场景，扩展到了页面、文档、白板、IDE 等一切多人协作的场景里。

从产品视角看，Presence 解决了三层问题。第一层是安全感——你知道队友在哪个文件里、最近有没有动过、是否掉线了；第二层是效率——光标位置、选区内容、正在编辑的字段，让两个人不用反复发消息确认"你改到哪了"；第三层是归属感——当屏幕上出现五六个颜色各异的光标同时移动时，你会产生一种"这不是我一个人的工作台，而是我们小组的工作台"的心理转变。第三层最容易被忽略，但对协同产品的留存和活跃，影响非常直接。

这篇博文适合三类人阅读：一是给自家 SaaS 产品加协同能力的全栈工程师，二是正在调研协作工具选型的产品经理，三是纯粹对"远程协作体验如何做成"感兴趣的技术爱好者。接下来我会先拆解 Presence 的能力组成，然后从零手写一个轻量实现，再讲前端渲染的感知设计，最后把我在真实项目里踩过的坑和边界设计一次说清楚。

2. Presence 到底在感知什么：一张能力地图拆解

如果你去查各类协同平台文档，会发现 Presence 相关配置项非常多，但底层能力归纳下来无非五类：在线状态、光标与选区、正在输入、成员身份、空间定位。把这五类分开理解，配置和开发时思路会清晰很多。

2.1 在线状态：不是简单的"在线/离线"

最基础的 Presence 是连接状态：当前用户在线还是离线，多久没活跃了。但真实业务里，"在线"的判定比想象中复杂。用户可能开着浏览器但切到了其他标签页，可能电脑合盖但浏览器进程未销毁，可能网络抖动导致 WebSocket 闪断重连——这些情况你都显示"在线"，会给队友错误信号。

我在项目里把在线状态拆成了三个等级：active（活跃中）——最近 30 秒内有鼠标、键盘、滚动等交互；idle（暂时离开）——超过 30 秒无交互，比如在查阅外部资料；offline（离线）——连接断开或超过 5 分钟无心跳。active 和 idle 之间通过前端交互事件动态切换，offline 则由服务端心跳超时兜底判定。这个分层逻辑用起来效果很好，队友之间能感知到"ta 还在但可能在忙别的"，而不是非黑即白。

2.2 光标与选区：最细粒度的"视觉接触"

光标位置是 Presence 里信息密度最高的元素。看文档协作产品（如 Google Docs）时你会发现，远端光标不仅显示坐标，还能高亮选中文字，甚至能看到对方操作的实时效果。这是因为光标背后跟着一个selection对象，包含 start、end 两个锚点。对于文档类应用，发送光标时一定要一并带上选区信息，否则对方无法知道你在"查看"一段文字还是在"修改"一段文字。

坐标采集有一个关键细节：必须发送相对坐标，而不是绝对坐标。不同屏幕分辨率、不同窗口大小下，绝对像素位置毫无意义。我通常把鼠标坐标换算成相对于当前可编辑容器或文档根节点的百分比坐标，接收端再乘以本地容器尺寸还原。这样即使双方窗口大小差异很大，光标也能落在大致正确的位置。

2.3 正在输入：延迟协作里的"心跳信号"

聊天框里的"对方正在输入"是 Presence 的经典应用，但在文档、代码编辑器、表单页里同样有价值。它解决的是协作中一个微妙的痛点：当你看到对方光标停在一个位置却迟迟没有输入时，你无法判断 ta 是在思考、在阅读、还是在发呆。有了输入状态，队友能感知到"ta 正在产生内容"，这会降低打断概率，也减少焦虑。

实现上，"正在输入"不要求实时高精度，一旦用户键入，本地马上置为输入中状态，通过节流广播给对方；用户停止输入 3 秒后，再广播一次"结束输入"。这样做的原因是：输入状态是突变的低频信号，不需要跟随每一次按键。我之前见过有人每次 keydown 都广播，结果 500ms 内发出几十条消息，除了制造噪声没有其他作用。

2.4 房间内的成员身份：Presence 的基本数据结构

每个 Presence 消息都必须携带可识别的身份信息，这决定了前端如何渲染、服务端如何路由。我习惯的最小集合是：

这里特别留意roomId。Presence 天然具备"圈层边界"：同一团队成员在同一文档中才需要互见光标，跨项目、跨科室就不应该互相看到。把 roomId 作为服务端广播路由的依据，是实现 Presence 的第一步。

2.5 空间定位：Presence 的"上下文锚点"

当你在一个长文档或白板里操作时，单纯知道队友在线还不够，你得知道"ta 在哪一块区域"。空间定位就是给 Presence 增加一个位置锚点：当前滚动偏移量、当前所在章节 ID、白板上的视口中心坐标。这一层常常被初学者忽略，但恰恰是它让 Presence 从"状态展示"升级为"场景协同"。

滚动位置同步有一个很反直觉的设计：不要直接把远端用户的 scrollTop 设置到你本地，否则你的页面会被别人拖着乱跑。正确做法是把队友的滚动位置显示为一个侧边缩略条上的颜色标记，提示"ta 在这个位置附近"，由你自己决定是否跳转。这也是所有成熟文档协作产品的通行做法——Presence 只负责让你知道发生了什么，施不施加影响应该永远由用户自己决定。

3. 从零搭一个轻量 Presence 服务：连接层与状态同步

聊完能力地图，我们动手做一个可用的轻量实现。我不打算引入重型云服务，而是用 Socket.IO + Redis 的方案，自己把 Presence 的状态同步逻辑沉淀下来。这样既能完全掌控数据，后面接任何房间、权限体系都方便。

3.1 为什么用 Socket.IO 而不是纯 WebSocket

很多人一上来就选原生 WebSocket，但对 Presence 场景来说，Socket.IO 省下的功夫远大于引入的成本。核心痛点有三个：断线自动重连、心跳保活、广播与确认。原生 WebSocket 这三块都得自己造轮子，而 Presence 对连接可靠性极其敏感——一次短暂的网络抖动如果导致光标全部离线，体验会瞬间崩塌。

Socket.IO 自带的 reconnection 策略会按指数退避重连，非常适合"合上电脑再打开"这种常见场景。配合服务端的心跳机制，离线判断的边界也能做得比较干净。当然，如果你所在技术栈已经接了成熟的实时层（比如你项目的推送已经是 gRPC-Stream 或 WebSocket 长连接），完全可以在现有通道上扩展 Presence 消息，不需要额外引入依赖。

3.2 连接生命周期与在线状态判定

先写服务端的基础骨架。我用的是 Node.js + Socket.IO + Redis，Redis 在这里承担两件事：存储每个 room 的在线成员快照，以及支持后续多实例水平扩展时的跨节点广播。

// server/presence.js import { Server } from "socket.io"; import Redis from "ioredis"; const redis = new Redis(process.env.REDIS_URL); const io = new Server({ cors: { origin: process.env.CORS_ORIGIN } }); const PRESENCE_KEY = (roomId) => `presence:${roomId}`; io.on("connection", (socket) => { const { userId, name, color, roomId } = socket.handshake.auth || {}; if (!userId || !roomId) { socket.disconnect(true); return; } socket.data.user = { userId, name, color, roomId }; // 加入房间，并广播成员加入事件 socket.join(roomId); socket.broadcast.to(roomId).emit("presence:join", socket.data.user); // 把在线成员写入 Redis 快照 const member = { ...socket.data.user, socketId: socket.id }; redis.sadd(PRESENCE_KEY(roomId), JSON.stringify(member)); // 把当前房间已有成员列表发给新加入者 const members = await redis.smembers(PRESENCE_KEY(roomId)); socket.emit("presence:members", members.map((m) => JSON.parse(m))); socket.on("presence:update", (payload) => { // 只允许更新自己的 Presence 数据 const enriched = { ...payload, ...socket.data.user, updatedAt: Date.now() }; socket.to(roomId).emit("presence:update", enriched); }); socket.on("disconnect", async () => { socket.to(roomId).emit("presence:leave", socket.data.user); await redis.srem(PRESENCE_KEY(roomId), JSON.stringify(member)); }); }); io.listen(3000);

这段代码有几个关键决定，我解释一下为什么这样写。handshake.auth 是我们从用户身份服务换取的一次性凭证，服务端 decode 后续传给 socket.data.user，防止前端伪造身份。成员列表放在 Redis 里是为了让新加入的用户能立刻看到"这个房间里已经有谁"，而不是等所有人再广播一次。

3.3 心跳与"僵尸连接"清理

有个坑几乎一定会踩：客户端没有正常走 disconnect，而是网络被硬切断，比如电梯里断网、电脑休眠。这种场景 Socket.IO 的 pingTimeout 机制会自动触发，但默认超时时间可能高达 20 秒——也就是说，队友会在你断网后将近 20 秒才看到你离线。对协作体验来说，20 秒太久了。

我调低了 pingTimeout 和 pingInterval：

const io = new Server({ pingInterval: 5000, // 每 5 秒发一次心跳 pingTimeout: 10000, // 10 秒没收到 pong 就判定离线 });

这样离线感知延迟控制在 10-15 秒之间。再配合前端的 pagehide 事件主动告知服务端离开，大部分场景都能做到秒级感知。这里有一句话值得记下来：Presence 的离线速度决定用户对系统的信任感，宁可误报一次离线，也不要让僵尸光标挂半小时。

3.4 客户端订阅与状态同步

客户端逻辑相对直接，重点在两点：维护本地成员 Map，以及用 rAF 节流渲染。

// client/presence.js import { io } from "socket.io-client"; export class PresenceClient { constructor({ url, auth, roomId }) { this.roomId = roomId; this.members = new Map(); this.socket = io(url, { auth: { ...auth, roomId } }); this.socket.on("presence:members", (members) => { members.forEach((m) => this.members.set(m.userId, m)); this.render(); }); this.socket.on("presence:join", (member) => { this.members.set(member.userId, member); this.render(); }); this.socket.on("presence:update", (update) => { const existing = this.members.get(update.userId); if (existing) { this.members.set(update.userId, { ...existing, ...update }); this.render(); } }); this.socket.on("presence:leave", (user) => { this.members.delete(user.userId); this.render(); }); } updatePresence(patch) { this.socket.emit("presence:update", patch); } }

这里有个很重要的细节：presence:update 的 payload 里，前端不允许传 userId，服务端必须从 connection 上下文里取。原因很简单——任何一个客户端都能伪造别人身份，把不存在的光标发进来。所有 Presence 数据，身份部分必须由服务端注入，客户端只能更新坐标、选区、输入状态这些"本事"字段。

4. 把"在场感"做进界面：多用户光标的视觉与防抖设计

服务端通了，光标能传了，但你以为就完了？真正拉开体验差距的，全在前端渲染这一层。多用户光标的画面，处理不好就是一场视觉灾难。

4.1 坐标采集与节点定位

鼠标在页面上的原始坐标是相对于浏览器窗口的 clientX/clientY，直接传出去肯定不行。我推荐把坐标锚定到具体的可编辑容器上。实现方式：监听 mousemove，用document.elementFromPoint(clientX, clientY)判断当前鼠标是否落在目标容器内，如果在，则计算相对坐标百分比。

function getRelativePosition(clientX, clientY) { const container = editorContainerRef.current; const rect = container.getBoundingClientRect(); return { x: (clientX - rect.left) / rect.width, y: (clientY - rect.top) / rect.height, inContainer: rect.left <= clientX && clientX <= rect.right && rect.top <= clientY && clientY <= rect.bottom, }; }

远程端拿到相对坐标后，反算绝对坐标，渲染一个绝对定位的远端口光标元素。这一步别自己做太多 DOM 操作，直接塞进一个 ref 属性更新就行。

4.2 节流窗口与 requestAnimationFrame

mousemove 每秒能触发几十上百次，无脑广播会造成两项开销：WebSocket 消息洪峰 + 页面上不必要的重绘。许多人想到的解决方案是"setInterval 每 100ms 发一次"，但 setInterval 的问题是它可能与浏览器的绘制帧错开，导致画面抖动。

推荐组合：mousemove 中只更新本地 state，用requestAnimationFrame统一读取最新坐标并发送。因为 rAF 本身就与浏览器刷新频率（通常 60fps）对齐，能保证你发送的坐标永远是最新的。

let rafId = null; let latestPoint = null; window.addEventListener("mousemove", (e) => { latestPoint = getRelativePosition(e.clientX, e.clientY); if (!rafId) { rafId = requestAnimationFrame(sendPresence); } }); function sendPresence() { rafId = null; if (latestPoint) { presenceClient.updatePresence({ cursor: latestPoint }); } }

实测下来，这样每秒最多发 60 条消息，绝大多数用户鼠标移动频率远低于此，实际网络负载可以忽略不计。如果你要同时广播选区信息，把 selection 也放进同一个 payload 里，一条消息搞定，不要拆成两种消息类型。

4.3 多用户光标的颜色分配与防重叠

给每个用户分配一个独一无二的颜色，看似简单，实际很容易撞色。我用的是一个基于 HSL 的固定色板算法：按 userId 哈希后取余，映射到 20 个明度适中的颜色中，然后把相近的颜色做区间隔离。

更值得操心的是多光标标签重叠问题。当两个用户的光标靠得很近，他们的名字标签会叠成一团，根本看不清谁是谁。我的解决方案是：渲染层对每个远端光标维护一个独立堆叠上下文，在绘制时检测当前光标位置与已渲染光标的距离，如果小于阈值（比如 24px），将后渲染的光标标签位置向上偏移。这就是经典的"标签防碰撞偏移"。

4.4 标签、动画与消失策略

远端口光标视觉上分两部分：小箭头和名字标签。箭头用 12px 的 SVG 折线实现，名字标签用圆角矩形 + 白字，跟随箭头左侧绘制。动画方面，我加了 120ms 的transition: left/top过渡，避免光标像素感太强。注意过渡时间别超过 150ms，否则远端光标的实时性会被削弱。

光标消失策略同样有讲究。不能一收到 presence:leave 就立刻移除——会显得非常生硬。我用的策略是：收到离开事件后，给光标元素加一个 300ms 的 opacity 渐隐动画，动画结束后再移除 DOM。这个 300ms 窗口内用户能感知到"ta 走了"这个动作，比瞬间消失更有自然的呼吸感。

4.5 体验层级：从"功能可用"到"感觉有人"

做了一阵子多用户光标后，我总结出一个三层体验模型。第一层是"正常的协作展示"——光标存在、位置准确、身份清晰，这属于功能层，做出来不难。第二层是"有节奏的反馈"——你能通过光标的移动频率、输入状态、选中范围，大致判断出队友的编辑节奏。第三层是最难的"氛围感"——让人在独自工作时，也能感受到旁边有一群并肩作战的人。

第三层其实不靠技术实现，靠的是产品设计。比如当房间里只有一个远端成员时，聊天浮层会提示"ta 已在这个页面停留 12 分钟"。当多人同时编辑同一段内容时，开启"冲突高亮"。这些设计需要持续观察用户行为数据，但方向是明确的：Presence 做得好，用户会不知不觉把在线协作者当成"同事"，而不是"功能"。

5. 在真实项目里，这套实现踩过的三个坑

任何实时协作功能，真正上线前都会遇到条件极其苛刻的边界场景。我挑三个最有代表性的问题，把排查链路展开讲讲，你们后面实现时可以提前规避。

5.1 离开页面后的"幽灵光标"

项目第一个版本上线后，用户反馈很多次：明明看到同事下线了，页面上却还有一个光标停在原地，怎么刷新都清不掉。排查链路是这样展开的。

第一步，我确认客户端确实收到了 presence:leave 事件。打印日志发现，收到事件时前端确实执行了members.delete(user.userId)。但问题在于——这个远端光标元素在前端框架中是通过 userId 关联渲染的，删除成员后，渲染层并没有主动卸载对应的光标 DOM，因为光标的渲染逻辑绑定在了一个独立的 cursorLayer 组件里，没有依赖 members Map。这就是前端状态依赖没有梳理干净的典型问题。

修复方案并不难：把远端光标渲染改写成完全受控组件，cursors 数组的唯一数据源就是members所对应的 cursor 字段，当成员被删除时，cursors 数组自然变小，DOM 也就会卸载。写成受控组件，这个问题从根本上就不会发生。

第二类幽灵光标更隐蔽：用户在多个标签页同时打开同一个文档，标签页 A 断线重连后，Socket.IO 创建了新的 socketId，但服务端那个旧的 socket 连接因为某种原因没有触发 disconnect，导致同一个 userId 在 Redis 快照里出现了两份。新加入的成员就会看到两个一模一样的用户。这类问题源于连接与身份没有建立唯一关联。我的修复是：服务端以 userId 为唯一键，新连接建立时强制踢掉同一 userId 的旧连接。代码示例如下。

// 在 connection handler 里 io.in(roomId).emit("presence:duplicate", { userId }); const existingSockets = await io.in(roomId).fetchSockets(); for (const sock of existingSockets) { if (sock.data.user?.userId === userId && sock.id !== socket.id) { sock.disconnect(true); } }

5.2 一个人出现在多人列表：同账户多标签页的合并策略

上述踢掉旧连接的做法有个副作用——用户在同一台电脑上开两个标签页，其中一个是空白标签页，另一个才是真正的文档页。此时空白标签页也会建立连接，并立刻把主标签页挤下线。这在自动登录的 SaaS 产品里很常见，用户会以为产品出 bug 了。

更合理的策略是允许多个 socket 属于同一个 userId，但在成员列表层面对同 userId 做"合并展示"。合并后的光标，只取最近活跃的那个 socket 的坐标，其他 socket 只作为保活后台连接。具体实现上，我在 Redis 里用 userId 作为 sorted set 的 key，每个 socketId 是 member，最后按心跳刷新时间取最新的那个为"活跃连接"。

这个方案还有额外好处：当主标签页意外挂起时，后台标签页不至于立刻把用户踢出房间，Presence 状态更稳定。

5.3 断线重连后的状态冲突与残留

Socket.IO 断线重连完成后，服务端连接上下文是全新的，但用户身份没有变。此时服务端需要做的动作是：重新广播 presence:join，并清理上一次连接留下的 Presence 残留。我之前遇到过一个 bug：用户网络闪断后自动重连，但 Redis 快照里还留着旧 socket 的 cursor 坐标，导致房间里出现一个停留在 5 分钟前位置的光标。

修复思路是给每个 socket 的 Presence 快照加connectionId（也就是 socketId），广播 update 时旧 socket 不再接收。服务端 disconnect 后同时清理 Redis 中该 socketId 对应的记录，不留二义性。保存的快速做法是每次广播前先redis.zrem或srem清掉旧 member，再写入新的。

5.4 服务端广播风暴：从单机到多实例的扩展预案

如果你只是一个小团队的自用工具，单机 Socket.IO 足够支撑几百个在线连接。但一旦做成 SaaS，多实例部署就会遇到广播跨节点问题——机器 A 上连接的用户的 Presence 数据，机器 B 上的用户得通过 Redis pub/sub 才能收到。

Socket.IO 官方提供了 Redis Adapter，一句话就能接上：

import { createAdapter } from "@socket.io/redis-adapter"; io.adapter(createAdapter(pubClient, subClient));

接上之后，广播会自动通过 Redis 转发到所有实例。但我必须提醒一句：Redis Adapter 只负责消息路由，不负责 Presence 数据的持久化。在线成员快照、活跃连接表、用户状态元数据，这些依然是你的业务数据，得自己存放。Redis Adapter 切多实例之后，至少要对presence:update的广播频率做整体评估，因为消息会从一个 socket 转发到多台机器上的多个房间成员，峰值可能呈指数增长。

6. 隐私、性能与优雅降级：Presence 的边界设计

Presence 是"看得见的协作"，但它必须是有边界的。某些数据能采集，能传输，但绝对不能展示；某些功能在低性能设备上要先降级；越是激进的协同体验，越需要一套严密的边界控制。

6.1 什么数据能采集：谨慎对待"语义内容"

光标坐标本质上是低敏感数据，但一旦你把选区内容、输入状态、当前编辑段落编号都接入 Presence，就要开始考虑隐私边界。我的原则是：

• 光标位置可以采集：它只有位置信息，没有语义内容。
• 选中范围可以采集：但只传 start/end 锚点，不传选中的文本内容。
• 正在输入状态可以采集：但明确只传"正在输入"这个布尔值，不传输入的缓冲文本。
• 当前编辑容器 ID 可以采集：这是空间锚点，但如果容器对应的是客户隐私数据字段名，建议过滤后传输。

简单说，Presence 应该只告诉别人"你在哪里活跃"，而不应该成为监听器。有人为了做"实时智能推荐"把用户输入内容实时广播，这已经越界了，在合规和数据伦理上都不推荐。

6.2 性能降级：网络差时如何保体验

Presence 是锦上添花型功能，绝不能拖累核心业务。当用户网络状况差时，Presence 消息会频繁积压，反而挤压 WebSocket 队列，导致编辑器本身的协同 CRDT 数据同步变慢。遇到这种情况，我建议做一个简单的自适应降级：

• 检测到 WebSocket 消息队列积压超过 200 条，暂停发送 cursor 坐标，只发"存在状态"心跳。
• 检测到连续 5 次心跳重连失败，完全关闭 Presence 广播，只保留本地编辑能力。
• 页面切换后台后，暂停发送所有非关键 Presence 更新，只有回到前台时立即同步一次。

在文章开头说的 Preview 那里，我补充一句：Presence 功能做得越好，对降级策略的要求也越高。真正常用的用户会依赖这种"看得见的协同"，一旦网络不稳，反而比没有 Presence 的产品体验落差更大。提前设计降级，是对用户负责。

6.3 权限与房间控制：Presence 不是全员可见

Presence 必须纳入权限体系。我们的产品里每个文档有三种角色：owner、editor、viewer。Presence 设计上，editor 和 owner 之间互见光标、选区与输入状态；viewer 默认为"匿名存在"——能看到其他人生成的内容，但自己的光标对别人完全不可见，也不能看到别人的光标。这个设定既保护了敏感审阅场景，又把 Presence 的体验价值聚焦在了真正的协作者之间。

房间控制上，同一文档在访客模式下不能展示在线成员列表；退出文档时强制断开 Presence 连接，不允许后台驻留。这些细节看似是权限题，实际是隐私设计的一部分。

7. 从功能上线到真正的"协作体温"

Presence 功能上线后，我做过一次用户回访。有一个用户留言让我印象很深："以前觉得团队远程写方案像是各写各的，现在打开编辑器看到几个光标在动，觉得大家确实在同一个文档空间里干活，心态不一样了。"这段话基本概括了 Presence 的价值——它不直接提升打字速度，但改变了用户对协作的心理预期。

如果你正在评估，上完 Presence 之后怎么判断它到底有没有用，我建议看三个指标加一个定性调研。指标层面：一是会话平均时长，二是多人同时编辑同一文档的比例，三是协作冲突的解决时长。经验数据是，上了光标/选区 Presence 之后，多人同时在线编辑的比例大约会提升 20%-40%。定性调研层面，直接问用户："你是否觉得队友在附近？"——这个问题的答案，才是 Presence 体验好坏的最终裁决。

最后分享一个小技巧。真正让"在场感"质感提升的，往往不是光标本身，而是配套的微交互：比如队友开始拖动滚动条时，侧边栏的迷你地图会显示一个跟着移动的半透明色块；比如队友完成一段编辑后，你会在行号旁看到一个短暂的"点击查看"气泡。这些设计不需要额外服务端能力，只需要在现有 Presence 数据之上加入业务语义。它们共同构成了产品独特的"协作体温"——这才是处处通用的 Presence 能力，最终在每个产品里长成不同模样的真正原因。