Realtimekit 常见陷阱

# RealtimeKit 常见问题与排查 ## 常见错误 ### "Cannot connect to meeting" (无法连接到会议) **原因：** 身份验证令牌无效/过期、API 凭据缺乏权限或网络阻止了 WebRTC **解决方案：** 验证令牌有效性，检查 API 令牌是否具有 **Realtime / Realtime Admin** 权限，为受限网络启用 TURN 服务 ### "No video/audio tracks" (无视频/音频轨道) **原因：** 未授予浏览器权限、未启用视频/音频、设备正在使用中或设备不可用 **解决方案：** 显式请求浏览器权限，验证初始化配置，使用 `meeting.self.getAllDevices()` 进行调试，关闭其他使用该设备的应用程序 ### "Participant count mismatched" (参与者人数不匹配) **原因：** `meeting.participants` 不包含 `meeting.self` **解决方案：** 总人数 = `meeting.participants.joined.size() + 1` ### "Events not firing" (事件未触发) **原因：** 监听器在操作后注册、事件名称错误或命名空间错误 **解决方案：** 在调用 `meeting.join()` 之前注册监听器，根据文档检查事件名称，验证命名空间是否正确 ### "CORS errors in API calls" (API 调用中的 CORS 错误) **原因：** 从客户端进行 REST API 调用 **解决方案：** 所有 REST API 调用**必须**在服务端（Workers、后端）进行。切勿向客户端公开 API 令牌。 ### "Preset not applying" (预设未应用) **原因：** 预设不存在、名称不匹配（区分大小写）或在预设创建前添加了参与者 **解决方案：** 通过仪表板或 API 验证预设是否存在，检查拼写和大小写，在添加参与者之前创建预设 ### "Token reuse error" (令牌重用错误) **原因：** 在不同会话中重用参与者令牌 **解决方案：** 每个会话生成新令牌。如果令牌在会话期间过期，请使用刷新端点。 ### "Video quality poor" (视频质量差) **原因：** 带宽不足、分辨率/比特率过高或 CPU 过载 **解决方案：** 降低 `mediaConfiguration.video` 的分辨率/帧率，监控网络状况，减少参与者人数或网格大小 ### "Echo or audio feedback" (回声或音频反馈) **原因：** 多个设备拾取相同的音频源 **解决方案：** - 降低 `mediaConfiguration.video` 的分辨率/帧率 - 监控网络状况 - 减少参与者人数或网格大小 ### 问题：回声或音频反馈 **原因**：多个设备拾取相同的音频源 **解决方案**： 在 `mediaConfiguration.audio` 中启用 `echoCancellation: true`，使用耳机，不说话时静音 ### "Screen share not working" (屏幕共享无法工作) **原因：** 浏览器不支持屏幕共享 API、权限被拒绝或 `displaySurface` 配置错误 **解决方案：