GraphQL 订阅连接调试指南

在 Zion 平台中，实时功能（如数据实时更新、多用户协同编辑等）依赖 GraphQL WebSocket 订阅。当实时订阅功能不工作时，需要调试 WebSocket 连接。

🔍 如何在浏览器里寻找它？

第一步：打开开发者工具

• 按 F12 或右键点击页面选择”检查”

第二步：进入 Network 标签

• 点击上方工具栏的 Network（网络）

第三步：过滤 WebSocket 类型

• 在过滤栏点击 Socket或WS（这是 WebSocket 的缩写）
• 如果看不到 WS 选项，点击过滤栏右侧的放大镜图标，手动输入 ws
• 找到名字为graphql-subscription的网络请求

第四步：查看 Messages（消息）

1. 点击左侧名为 graphql-subscription 的条目
2. 点击右侧出现的 Messages 选项卡
3. 这里会显示所有 WebSocket 消息

📥 调试时的三类”关键信息”

在 Messages 窗口里，你会看到一排向上和向下的箭头：

🟢 绿色向上箭头↑：发送给订阅的数据

你会看到：

{ "type": "connection_init" }

含义：这是你的浏览器在给服务器打招呼：“我准备好了，这是我的通行证（authToken）”。

完整消息示例：

{
  "type": "connection_init",
  "payload": {
    "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

🔴 红色向下箭头↓（Down）：订阅返回的数据

你会看到：

{ "type": "ka" }

含义：这是服务器在定期发脉搏：“别断开，我还在呢”（Keep Alive）。

调试意义：

• 如果看不到 ka 消息，说明连接可能已断开
• 正常的订阅连接应该每隔一段时间（通常 10-30 秒）收到一次心跳
• 看到 ka 都代表脉搏正常

📥 订阅到的数据（Data）

这就是最重要的部分！每当你在 Zion 后台改了数据，这里会弹出一个新的消息：

{
  "type": "data",
  "id": "subscription-1",
  "payload": {
    "data": {
      "blog_article": [
        {
          "id": "123",
          "title": "新文章标题",
          "content": "文章内容..."
        }
      ]
    }
  }
}

调试重点：

• 看到 type: "data" 就说明订阅成功了！
• 检查 payload.data 里是否有你期望的数据
• 如果没数据，检查订阅的 query 和 variables 是否正确

🚨 调试常见问题（小白避坑指南）

Q1: 为什么我看不到 graphql-subscription 连接？

可能原因：

1. 过滤错了：确认点击的是 WS 过滤按钮，不是 Fetch/XHR
2. 没触发订阅：订阅是在页面加载或某个操作后才会建立，刷新页面试试
3. 订阅未配置：检查 Zion 编辑器中数据源的请求类型是否为订阅

解决方法：

1. F12 打开开发者工具
2. 切换到 Network 标签
3. 点击 WS 过滤
4. 刷新页面（F5）
5. 等待几秒，看是否出现 graphql-subscription

Q2: 为什么连接断开了

常见原因：

Q3: 为什么我看不到数据弹出来？

排查步骤：

第一步：检查连接状态

• 如果 graphql-subscription 条目变红了，说明断开了
• 通常是由于登录过期（Token 没传对）

第二步：看 Payload（载荷）

点击 Messages 里的订阅请求消息，检查 query 部分：

{
  "type": "start",
  "id": "subscription-1",
  "payload": {
    "query": "subscription { ... }",
    "variables": {
      "where": {
        "role": "主管" // ❌ 如果传了"员工"，服务器就不会推数据给你
      }
    }
  }
}

常见错误：

• where 条件写错了（比如想看”主管”的数据却传了”员工”）
• variables 参数缺失或格式错误
• query 里订阅的表名或字段名不对

第三步：检查服务器端

• 确认后台数据确实发生了变化（手动改一条数据试试）

Q4: 连接成功但一直没数据？

可能原因：

1. 没人对数据做修改：订阅只推送”变化的数据”，没人改数据就不会有消息
2. 订阅条件过滤太严格：where 条件导致没有匹配的数据变化
3. 权限问题：当前用户无权查看该数据

测试方法： 在数据库中手动修改一条订阅相关的数据，看 WebSocket Messages 里是否立即有新消息弹出。

成功情况：

🟢 {"type":"connection_init"}
🔴 {"type":"ka"}
📥 {"type":"data", "id":"1", "payload": {"data": {...}}}

看到 type: "data" 就说明订阅正常工作！

失败情况：

🟢 {"type":"connection_init"}
🔴 {"type":"ka"} 或 {"type":"ping"}
❌ {"type":"error", "payload": {"message": "..."}}

看到 type: "error" 就说明订阅有问题，查看 payload.message 获取错误信息。

🎯 总结给用户的一句话

“调试订阅，就是去 Network 的 WS 选项卡里看 Messages。只要有新消息（type: "data"）跳出来，你的实时功能就是通的！“

相关工具和资源

开发者工具技巧

相关文档

• 异常和错误的诊断方法 - 通用调试技巧
• 错误信息字典 - 常见错误对照表
• 使用 AI 助手进行调试 - AI 辅助排查