Realtime Sfu 常见陷阱

# 常见问题与排查 ## 常见错误 ### "初始连接缓慢 (~1.8s)" **原因：** 在共识形成期间首次 STUN 延迟（正常行为） **解决方案：** 后续连接会更快。CF 会提前检测 DTLS ClientHello 以进行补偿。 ### "无媒体流" **原因：** SDP 交换不完整，连接未建立，在 offer 前未添加轨道，浏览器权限缺失 **解决方案：** 1. 验证 SDP 交换是否完成 2. 检查 `pc.connectionState === 'connected'` 3. 确保在创建 offer 前已添加轨道 4. 确认已授予浏览器权限 5. 使用 `chrome://webrtc-internals` 进行调试 ### "轨道未接收" **原因：** 轨道未发布，轨道 ID 未共享，会话 ID 不匹配，未设置 `pc.ontrack`，需要重新协商 **解决方案：** 1. 验证轨道是否发布成功 2. 确认轨道 ID 已在对等端之间共享 3. 检查会话 ID 是否匹配 4. 在 answer 前设置 `pc.ontrack` 处理程序 5. 如有必要，触发重新协商 ### "ICE 连接失败" **原因：** 网络变更，防火墙阻止 UDP，需要 TURN，瞬时网络问题 **解决方案：** typescript pc.oniceconnectionstatechange = async () => { if (pc.iceConnectionState === 'failed') { console.warn('ICE 失败，尝试重启'); await pc.restartIce(); // 触发新的 ICE 收集 // 创建带有 ICE 重启标志的新 offer const offer = await pc.createOffer({iceRestart: true}); await pc.setLocalDescription(offer); // 发送到后端 → Cloudflare API await fetch(`/api/sessions/${sessionId}/renegotiate`, { method: 'PUT', body: JSON.stringify({sdp: offer.sdp}) }); } }; ### "轨道卡顿/冻结" **原因：** 发送方暂停了轨道，网络拥塞，编解码器不匹配，移动端浏览器切入后台 **解决方案：** 1. 检查 `track.enabled` 和 `track.readyState === 'live'` 2. 验证发送方是否活跃：`pc.getSenders().find(s => s.track === track)` 3. 检查丢包/抖动统计信息（参见 patterns.md） 4. 在移动端：当应用回到前台时重新获取轨道 5. 如果问题持续，尝试使用不同的编解码器 ### "网络切换导致通话断开" **原因：** 移动端在 WiFi 和蜂窝网络间切换，笔记本电脑切换网络 **解决方案：** typescript // 监听网络变化 if ('connection' in navigator) { (navigator as any).connection.addEventListener('change', async () => { console.log('网络已变更'); await pc.restartIce(); // 使用上述 ICE 重启模式 }); } // 或者使用 PartyTracks (自动处理)