Skip to content

Realtime: Isolating Server-Side vs. Client-Side Issues with Inspector and DevTools

Last edited: 10/14/2026

当一个通道看起来订阅成功，但客户端始终没有收到 broadcast 消息、presence 更新或 postgres_changes 事件时，请使用本指南。这些步骤可以帮助你确定问题出在服务器、客户端代码，还是客户端的网络。

🌐 Use this guide when a channel appears to subscribe successfully but the client consistently receives no broadcast messages, presence updates, or postgres_changes events. These steps help you determine whether the issue is on the server, in the client code, or in the client's network.

本指南不涵盖延迟到达或间歇性丢失的事件。这些情况可能表示其他问题，比如复制延迟或连接不稳定。

🌐 This guide does not cover events that arrive late or are dropped intermittently. Those symptoms may indicate a different issue, such as replication lag or an unstable connection.

步骤 1：使用实时检查器验证服务器端投递 #

🌐 Step 1: Verify server-side delivery with Realtime Inspector

打开 实时检查器，然后选择你正在调试的功能。

🌐 Open Realtime Inspector and select the feature you are debugging.

  1. 对于 postgres_changes，输入你的应用使用的相同模式、表、事件类型和过滤器。以 postgres 身份连接，然后执行与你的事件类型和过滤器匹配的实际更改，例如如果你在测试 INSERT，就插入一个满足过滤器的行。查看事件是否出现在检查器中。
  2. 以与你的应用相同角色的已认证用户身份重复测试。这可以揭示在以 postgres 测试时看不到的 RLS 或授权问题。
  3. 对于 broadcast 或 presence，根据通道类型进行测试：
    • 公开通道： 不会进行授权检查，所以仅以 postgres 测试。
    • **私有通道：**以 postgres 和已验证用户身份进行测试。使用与你的应用发送的会话匹配的会话。

对于 broadcast，你可以直接从 Inspector 触发消息。对于 presence，Inspector 只能观察通道；track() 调用必须从你这边发起，所以先在同一个通道名上打开 Inspector，然后从你的应用触发 track()，并确认状态在 Inspector 中出现。

🌐 For broadcast, you can trigger the message directly from Inspector. For presence, Inspector can only observe the channel; the track() call has to come from your end, so open Inspector on the same channel name first, then trigger track() from your app and confirm that the state appears in Inspector.

如果测试失败为 postgres：

  • 有关 postgres_changes，请参见 实时：Postgres 更改故障排除。它涵盖了发布成员资格和其他服务器端配置。
  • 对于 broadcast 或 presence，失败发生在授权之前。确认触发器或发送调用是否在执行。

如果测试作为 postgres 成功，但作为已认证用户失败：

  • postgres_changes 的问题很可能与 RLS 有关。请参阅 实时：Postgres 更改故障排除 获取测试和修复策略的指导。
  • 对于 broadcast 或 presence，问题很可能与该角色在 realtime.messages 上的通道授权有关。查看 实时授权文档中的策略示例。还要检查是否复杂的策略导致授权检查运行缓慢或超时。

如果两个测试都成功： 实时服务器和 Postgres 正常工作。问题很可能出在客户端或网络路径上。继续进行步骤 2。

第2步：检查客户端配置 #

🌐 Step 2: Check the client configuration

检查这些常见的配置问题：

🌐 Check for these common configuration issues:

  • postgres_changes： 确认过滤器、模式、表和事件类型是否匹配。有关常见不匹配情况，请参阅 Realtime: Postgres Changes Troubleshooting 的“检查订阅代码本身”部分。
  • broadcast： 确认发送方和接收方使用相同的主题和事件名称。
  • **presence：**确认在通道达到SUBSCRIBED后调用了track()，并且所有客户端使用相同的通道名称。

还要确保你正在使用最新版本的 @supabase/supabase-js，如果单独固定了 @supabase/realtime-js，也要确保是最新版本。旧版本可能有漏洞，会导致事件丢失。

🌐 Also make sure you are using a recent version of @supabase/supabase-js and, if pinned separately, @supabase/realtime-js. Older versions may contain bugs that cause events to be dropped.

如果配置和软件包版本正确，但事件仍未到达，继续进行第3步。

🌐 If the configuration and package versions are correct but events still do not arrive, continue to Step 3.

步骤 3：在浏览器开发者工具中检查连接流量 #

🌐 Step 3: Inspect connection traffic in browser developer tools

  1. 在 Chrome 中打开你的应用，然后在该标签页打开开发者工具，进入网络（Network）标签。
  2. 在你的应用里触发启动实时连接的操作。找到连接到 wss://<project-ref>.supabase.co/realtime/v1/websocket 的地方。（注意：如果你的应用在页面加载时就连接，请在打开开发者工具的情况下刷新页面。）
  3. 选择连接，然后打开消息标签。
  4. 找到最初的 phx_join 消息及其对应的 phx_reply。
  5. 保持连接一到两分钟，以捕捉心跳和其他流量。
  6. 触发预期的事件，例如，插入一行、发送广播或跟踪存在情况。

利用捕获的消息来确定发生了什么，然后采取相应的行动：

🌐 Use the captured messages to determine what happened, then act accordingly:

  • 已加入通道，但服务器从未发送事件: 订阅与步骤1中测试的不匹配。请根据步骤2重新检查。
  • 服务器发送了事件，但应用没有处理它: 问题出在客户端处理器，而不是订阅配置。检查回调中是否有抛出的错误或被拒绝的 Promise，可能被悄悄吞掉了。
  • WebSocket 连接根本没有完成： 继续到步骤 4。

第4步：检查网络路径 #

🌐 Step 4: Check the network path

确认对 wss://.../realtime/v1/websocket 的 WebSocket 请求收到了 101 Switching Protocols 响应。

🌐 Confirm that the WebSocket request to wss://.../realtime/v1/websocket receives a 101 Switching Protocols response.

如果没有，或者控制台报告 TLS 或证书错误，可能是防火墙、代理或 SSL 检查网络设备在连接到 Realtime 之前就阻止了连接。

🌐 If it does not, or if the console reports a TLS or certificate error, a firewall, proxy, or SSL-inspecting network appliance may be blocking the connection before it reaches Realtime.

试着在完全不同的网络上测试同一个应用，看看问题是不是网络相关的。

🌐 Try testing the same app on a completely different network to confirm if the issue is network-specific.

如果你仍然需要帮助，联系支持 并包含问题的描述、这些测试的相关结果，以及你已经尝试的故障排查步骤。这些信息将有助于缩小问题的原因范围。

🌐 If you still need help, contact Support and include a description of the issue, relevant results of these tests, and the troubleshooting steps you've already tried. This information will help narrow down the cause.