Realtime: ClientPresenceRateLimitReached error
Last edited: 8/12/2026
如果客户过于频繁地发送在线状态更新，你可能会在你的 实时日志 中看到此错误代码：
🌐 If a client sends Presence updates too frequently, you may see this error code in your Realtime logs:
1ClientPresenceRateLimitReached在客户端，该通道接收到一个 system 错误消息后就会被关闭。该通道上的任何 Presence、Broadcast 或 Postgres Changes 订阅都会停止，直到客户端重新连接。
🌐 On the client side, the channel receives a system error message and is then closed. Any Presence, Broadcast, or Postgres Changes subscriptions on that channel stop until the client reconnects.
这个错误几乎总是意味着 Presence 被用在了它不适合的高频更新上。这个指南解释了限制是什么、为什么存在，以及如何修复它。
🌐 This error almost always means Presence is being used for high-frequency updates that it isn't designed for. This guide explains the limit, why it exists, and how to fix it.
错误为什么会发生 #
🌐 Why the error occurs
每个客户端在每个连接上都有发送在线状态更新的频率限制。默认情况下，客户端最多可以在30秒内发送5次在线状态更新。track() 和 untrack() 的调用都会计入这个限制。当客户端超过这个限制时，实时系统会记录 ClientPresenceRateLimitReached 并关闭通道。
🌐 Each client has a per-connection limit on how often it can send Presence updates. By default, a client can send at most 5 Presence updates within a 30-second window. Both track() and untrack() calls count toward this limit. When a client exceeds it, Realtime logs ClientPresenceRateLimitReached and shuts the channel down.
这是针对每个客户端的保护措施，它与整个项目每秒的在线事件限制（记录为 PresenceRateLimitReached）是分开的。即使整体项目使用量很低，单个客户端也可能自己达到 ClientPresenceRateLimitReached。
🌐 This is a per-client safeguard, and it is separate from the project-wide presence events per second limit (logged as PresenceRateLimitReached). A single client can hit ClientPresenceRateLimitReached on its own, even when overall project usage is low.
这个限制存在是因为 Presence 会通过服务器同步状态，并在每次更改时通知通道上的每一个订阅者。一个客户端如果在循环里频繁调用 track()——比如每次鼠标移动时共享光标位置——就会把更新放大到所有订阅者，从而影响通道的整体性能。速率限制就是为了防止一个客户端做这种事。
🌐 The limit exists because Presence syncs state through the server and notifies every subscriber on the channel on each change. A client that calls track() in a tight loop—for example, on every mouse move to share a cursor position—multiplies its updates across all subscribers and degrades the channel for everyone. The rate limit stops one client from doing this.
怎么修好它 #
🌐 How to fix it
解决方法是停止频繁发送在线状态更新。选择一个适合你使用情况的选项。
🌐 The fix is to stop sending frequent Presence updates. Choose the option that matches your use case.
使用广播进行高频更新 #
🌐 Use Broadcast for high-frequency updates
存在状态适用于变化比较慢的状态，比如在线/离线状态、用户正在查看的文档，或者他们所在的页面。对于高频率或一次性发送的数据——比如实时光标、输入指示器、指针位置——则使用 Broadcast。Broadcast 通过 Realtime 向连接的客户端传递消息，而不维护同步的存在状态，因此可以处理快速更新而不会触发这个限制。
🌐 Presence is meant for slow-changing state such as online/offline status, the document a user is viewing, or which page they're on. For high-frequency or fire-and-forget data—live cursors, typing indicators, pointer positions—use Broadcast instead. Broadcast relays messages through Realtime to connected clients without maintaining synced Presence state, so it handles rapid updates without triggering this limit.
限制你的在线状态更新 #
🌐 Throttle your Presence updates
如果你确实需要用于经常变化的状态的 Presence，就对你的 track() 和 untrack() 调用进行节流，让客户端每个窗口最多发送几次 Presence 更新。只有在共享状态发生变化时才更新 Presence，并将突发的更新合并成一次，而不是在每个事件上都发送一次。
🌐 If you do need Presence for state that changes often, throttle your track() and untrack() calls so the client sends at most a few Presence updates per window. Only update Presence when the shared state changes, and coalesce bursts into a single update rather than sending one on every event.
如何预防它 #
🌐 How to prevent it
- 保留 Presence 用于变化缓慢的状态，快速更新的内容则使用 Broadcast。具体指南请参见 Presence 指南。
- 只有在共享状态变化时才调用
track()，不要用定时器或者每个输入事件都调用。
相关资源 #
🌐 Related resources