第27章 WebRTC调试

课程目录第27章 WebRTC调试

27、WebRTC调试：常见错误排查、日志分析、网络抓包与SDP调试

WebRTC 开发，说白了就是跟网络环境、浏览器差异、信令交互这些「不确定性」打交道。我做了这么多年实时通信，最深的体会就是：调试能力决定了你解决问题的速度。这一章，我把实战中积累的调试套路全盘托出，从日志到抓包，从 SDP 到 ICE，咱们一步步来。

核心调试三板斧：日志分析（找线索）→ 网络抓包（看细节）→ SDP 调试（定根源）。这三步走完，90% 的问题都能定位。

27.1 常见错误类型与排查思路

先说说我遇到最多的几类错误。嗯，这里我按出现频率排个序：

错误类型	典型表现	常见原因
连接失败	iceConnectionState 卡在 checking	STUN/TURN 配置错误、防火墙拦截
媒体不通	远端黑屏/无声，但连接状态正常	SDP 中媒体方向错误、编解码器不匹配
信令异常	Offer/Answer 交换后无响应	信令服务器逻辑错误、JSON 格式问题
浏览器兼容	Chrome 正常，Safari 不行	编解码器支持差异、Simulcast 参数不同

排查的时候，我习惯先看 iceConnectionState 和 iceGatheringState 的变化。这两个状态机就像交通信号灯，告诉你连接走到哪一步了。

// 监听连接状态变化
peerConnection.oniceconnectionstatechange = (event) => {
  console.log('ICE 状态:', peerConnection.iceConnectionState);
  // 常见状态: new, checking, connected, completed, failed, disconnected, closed
  if (peerConnection.iceConnectionState === 'failed') {
    console.error('ICE 连接失败，检查 STUN/TURN 配置');
  }
};

peerConnection.onicegatheringstatechange = (event) => {
  console.log('ICE 收集状态:', peerConnection.iceGatheringState);
  // new, gathering, complete
};

我的小技巧：在控制台把这两个状态变化打印出来，配合时间戳，能快速判断是「收集阶段」还是「连接阶段」出了问题。我曾经遇到一个 case，STUN 服务器配置错了，ICE 收集一直卡在 gathering，日志一看就明白了。

27.2 日志分析：从浏览器控制台到 RTCPeerConnection 统计

日志是调试的第一道防线。浏览器控制台会输出很多有用信息，但很多人忽略了 getStats() 这个 API。它返回的是实时统计信息，比看控制台日志更直接。

// 获取统计信息
async function getConnectionStats(pc) {
  const stats = await pc.getStats();
  stats.forEach(report => {
    if (report.type === 'candidate-pair' && report.state === 'succeeded') {
      console.log('选中的候选者对:', report.localCandidateId, report.remoteCandidateId);
      console.log('RTT:', report.currentRoundTripTime, 'ms');
    }
    if (report.type === 'inbound-rtp') {
      console.log('接收码率:', report.bytesReceived / (report.timestamp - report.lastTimestamp) * 8, 'bps');
      console.log('丢包率:', report.packetsLost / report.packetsReceived * 100, '%');
    }
  });
}

// 每隔 2 秒采集一次
setInterval(() => getConnectionStats(peerConnection), 2000);

我个人习惯把 getStats() 的数据格式化后输出到控制台，或者直接上传到后台做监控。你看，丢包率超过 5% 就要警惕了，超过 10% 基本就会影响通话质量。

注意：getStats() 返回的数据结构在不同浏览器中略有差异。Chrome 和 Firefox 的字段名可能不同，建议先打印出来看看结构。我曾经在 Safari 上踩过坑，它返回的 type 命名跟 Chrome 不一样。

27.3 网络抓包：用 Wireshark 看透 ICE 和 DTLS

日志只能看到应用层的信息，网络层面的问题还得靠抓包。Wireshark 是我最常用的工具，配合 tcpdump 在服务器端抓包，基本能覆盖所有场景。

抓包时重点关注三个协议：

STUN：看 Binding Request/Response 是否正常，判断 NAT 类型
DTLS：看握手是否完成，证书是否匹配
SRTP/SRTCP：看媒体数据是否加密传输

Wireshark 有个很实用的过滤规则：

# 只显示 STUN 和 DTLS 包
stun || dtls

# 显示特定 IP 的 RTP 流
ip.addr == 192.168.1.100 && rtp

# 过滤 ICE 候选者相关的 STUN 包
stun && stun.type == 0x0001  # Binding Request

我记得有一次线上问题，用户反馈通话断断续续。日志看了一圈没发现异常，最后抓包发现 STUN Binding Response 的 RTT 高达 800ms，原来是用户连的海外 TURN 服务器延迟太高。换了个就近的节点就解决了。

抓包小贴士：在 Chrome 中开启 chrome://webrtc-internals，可以导出完整的 ICE 事件日志，包括候选者优先级、排序过程等。这个页面导出的 JSON 文件可以直接导入 Wireshark 做关联分析。

27.4 SDP 调试：读懂 Offer/Answer 中的关键字段

SDP 是 WebRTC 的「灵魂」。很多媒体问题，说白了就是 SDP 没写对。我见过太多人一看到 SDP 就头疼，其实只要抓住几个关键字段就行。

先看一个典型的 SDP Offer：

v=0
o=- 1234567890 2 IN IP4 0.0.0.0
s=-
t=0 0
a=group:BUNDLE 0 1
a=msid-semantic: WMS

m=audio 9 UDP/TLS/RTP/SAVPF 111 103 104 9 0 8
c=IN IP4 0.0.0.0
a=rtcp:9 IN IP4 0.0.0.0
a=ice-ufrag:abc123
a=ice-pwd:def456
a=fingerprint:sha-256 12:34:56:78:9A:BC:DE:F0...
a=setup:actpass
a=mid:0
a=sendrecv
a=rtpmap:111 opus/48000/2
a=rtpmap:103 ISAC/16000
a=ssrc:123456789 cname:test

m=video 9 UDP/TLS/RTP/SAVPF 96 97 98
c=IN IP4 0.0.0.0
a=rtcp:9 IN IP4 0.0.0.0
a=ice-ufrag:abc123
a=ice-pwd:def456
a=fingerprint:sha-256 12:34:56:78:9A:BC:DE:F0...
a=setup:actpass
a=mid:1
a=sendrecv
a=rtpmap:96 VP8/90000
a=rtpmap:97 VP9/90000
a=rtpmap:98 H264/90000
a=ssrc:987654321 cname:test

调试 SDP 时，我重点看这几个地方：

字段	含义	常见问题
`m=` 行	媒体类型和端口	端口为 0 表示禁用该媒体，检查是否误设
`a=ice-ufrag/pwd`	ICE 认证凭据	Offer 和 Answer 必须不同，否则连接失败
`a=fingerprint`	DTLS 证书指纹	两端指纹必须匹配，否则 DTLS 握手失败
`a=sendrecv`	媒体方向	如果一端是 `sendonly`，另一端必须是 `recvonly`
`a=rtpmap`	编解码器映射	两端必须至少有一个共同编解码器

调试技巧：在 createOffer() 或 createAnswer() 的回调中，把 SDP 打印出来，手动对比两端的关键字段。我曾经遇到一个 case，Answer 端把 a=setup:actpass 改成了 a=setup:passive，导致 DTLS 握手一直失败。这种问题看日志根本看不出来，一对比 SDP 就发现了。

27.5 实战：一个完整的调试流程

假设你现在遇到一个问题：两个用户在同一个局域网内，但 WebRTC 连接就是建立不起来。我会按这个流程走：

看控制台：打开 chrome://webrtc-internals，看 ICE 状态是否卡在 checking。如果是，说明候选者没配对成功。
检查网络：用 ping 测试两端是否互通。局域网内一般没问题，但有些公司网络有隔离策略。
抓包分析：在两端同时抓包，看 STUN Binding Request 是否发出，Response 是否返回。如果只有 Request 没有 Response，说明防火墙拦截了 UDP 包。
对比 SDP：把两端的 SDP 打印出来，检查 ice-ufrag、fingerprint、rtpmap 是否匹配。
降级测试：强制使用 TURN 服务器，看是否能连通。如果能，说明是 P2P 直连的问题，大概率是 NAT 或防火墙。

这个流程我用了好几年，基本没失手过。你想想看，调试就像破案，线索就在日志、抓包和 SDP 里，关键是你得知道去哪找。

避坑指南：我曾经在调试一个跨网段连接时，花了两个小时才发现是 STUN 服务器的 DNS 解析有问题。浏览器缓存了错误的 IP，导致 STUN 请求一直发到错误的地址。所以，先检查 DNS 解析，用 nslookup 或 dig 确认 STUN/TURN 服务器的 IP 是否正确。

27.6 知识体系总览

下面这张图总结了本章的核心调试思路，从问题出现到定位根源的完整链路：

这张图把调试流程分成了三层。第一层是问题出现，第二层是三个排查方向，第三层是每个方向的关键检查点，最后汇聚到定位根源。我建议你在实际工作中也按这个思路来，别一上来就抓包，先看日志，再决定下一步。

调试 WebRTC 其实没那么玄乎。记住三个关键词：日志、抓包、SDP。遇到问题别慌，按流程走一遍，大部分问题都能在半小时内定位。嗯，这一章的内容就到这里，希望对你有所帮助。

📚 课程目录

27、WebRTC调试：常见错误排查、日志分析、网络抓包与SDP调试

27.1 常见错误类型与排查思路

27.2 日志分析：从浏览器控制台到 RTCPeerConnection 统计

27.3 网络抓包：用 Wireshark 看透 ICE 和 DTLS

27.4 SDP 调试：读懂 Offer/Answer 中的关键字段

27.5 实战：一个完整的调试流程

27.6 知识体系总览