30、综合实战：搭建完整的 WebRTC 调试环境，从信令到媒体流全链路排查问题

说实话，WebRTC 调试是我见过最让人头疼的事情之一。信令、NAT 穿透、媒体协商、编解码器……任何一个环节出问题，视频就是黑的，音频就是哑的。我早期做项目时，经常花一整天就为了查一个“对方看不到我”的问题。后来我总结了一套完整的调试环境搭建方法，今天全部分享给你。

这一章，我们从头到尾搭一个能用的调试环境。不是那种“Hello World”级别的 demo，而是真正能用来排查线上问题的工具箱。

30.1 调试环境的整体架构

先看整体结构。我习惯把调试环境分成三层：

说白了，调试就是一层一层往下挖。信令层出问题，媒体层根本跑不起来。我见过太多人一上来就查编解码器，结果发现是 SDP 没传过去——白费功夫。

30.2 搭建信令调试工具

信令是 WebRTC 的“指挥系统”。指挥系统乱了，后面全是乱的。

30.2.1 信令日志中间件

我个人习惯在信令服务器上加一个日志中间件。不管用 Socket.IO 还是原生 WebSocket，都统一拦截所有消息。

// 信令日志中间件示例
function signalingLogger(socket, next) {
  const originalEmit = socket.emit.bind(socket);
  socket.emit = function(event, data) {
    console.log(`[SEND] ${event}`, JSON.stringify(data, null, 2));
    // 同时写入本地日志文件
    logToFile(`[SEND] ${event}`, data);
    return originalEmit(event, data);
  };

  socket.onAny((event, data) => {
    console.log(`[RECV] ${event}`, JSON.stringify(data, null, 2));
    logToFile(`[RECV] ${event}`, data);
  });

  next();
}

30.2.2 SDP 可视化分析器

SDP 文本看着头疼？我写了一个简单的解析器，把 SDP 转成表格。

// SDP 解析函数（简化版）
function parseSDP(sdpText) {
  const lines = sdpText.split('\n');
  const result = {
    media: [],
    ice: {},
    dtls: {}
  };
  
  let currentMedia = null;
  
  lines.forEach(line => {
    if (line.startsWith('m=')) {
      currentMedia = {
        type: line.split(' ')[1],
        port: line.split(' ')[2],
        protocols: line.split(' ')[3],
        codecs: line.split(' ').slice(4)
      };
      result.media.push(currentMedia);
    } else if (line.startsWith('a=ice-ufrag')) {
      result.ice.ufrag = line.split(':')[1];
    } else if (line.startsWith('a=ice-pwd')) {
      result.ice.pwd = line.split(':')[1];
    } else if (line.startsWith('a=fingerprint')) {
      result.dtls.fingerprint = line.split(' ')[1];
    }
  });
  
  return result;
}

解析后的结果，我习惯用表格展示：

媒体类型	端口	协议	编解码器列表
audio	9	UDP/TLS/RTP/SAVPF	111(opus), 103(ISAC), 9(G722)
video	9	UDP/TLS/RTP/SAVPF	96(VP8), 97(VP9), 98(H264)

30.3 传输层调试：ICE 与 NAT 穿透

传输层是 WebRTC 最复杂的部分。ICE 状态机、候选者收集、NAT 穿透……任何一个环节出问题，连接就建立不起来。

30.3.1 使用 chrome://webrtc-internals

这个工具是 Chrome 自带的，但很多人不知道怎么用。我教你一个排查流程：

1. 打开 chrome://webrtc-internals
2. 点击“Create”开始录制
3. 发起 WebRTC 连接
4. 观察 ICE Connection State 的变化

ICE 状态机有这几个状态：

状态	含义	常见问题
checking	正在检查候选者	卡在这里说明候选者收集不全
connected	已建立连接	正常状态
completed	所有候选者检查完毕	正常状态
failed	连接失败	检查 STUN/TURN 配置
disconnected	连接断开	网络波动或超时

30.3.2 候选者配对分析

ICE 候选者配对是另一个容易出问题的地方。我写了一个小工具来可视化候选者配对过程：

// 候选者配对分析
function analyzeCandidates(localCandidates, remoteCandidates) {
  const pairs = [];
  
  localCandidates.forEach(local => {
    remoteCandidates.forEach(remote => {
      // 检查地址族是否匹配
      if (local.addressType !== remote.addressType) {
        console.warn(`地址族不匹配: ${local.addressType} vs ${remote.addressType}`);
        return;
      }
      
      // 检查传输协议
      if (local.transport !== remote.transport) {
        console.warn(`传输协议不匹配: ${local.transport} vs ${remote.transport}`);
        return;
      }
      
      pairs.push({
        local: `${local.ip}:${local.port}`,
        remote: `${remote.ip}:${remote.port}`,
        type: `${local.type}-${remote.type}`,
        priority: calculatePriority(local, remote)
      });
    });
  });
  
  return pairs.sort((a, b) => b.priority - a.priority);
}

你想想看，如果本地只有 host 候选者，远程只有 relay 候选者，那配对优先级会很低。我遇到过一种情况：双方都在同一个内网，但 ICE 却走了 TURN 中继，延迟高得离谱。后来发现是 host 候选者被防火墙拦截了。

30.4 媒体层调试：getStats 与质量分析

媒体层的问题最直观——画面卡顿、音画不同步、马赛克。但原因可能藏在底层。

30.4.1 getStats API 实战

getStats 是 WebRTC 的“体检报告”。我习惯每 5 秒拉一次数据：

// 定期获取统计信息
function startStatsMonitor(pc, interval = 5000) {
  setInterval(async () => {
    const stats = await pc.getStats();
    
    stats.forEach(report => {
      if (report.type === 'inbound-rtp' && report.kind === 'video') {
        console.log(`视频接收统计:`);
        console.log(`  帧率: ${report.framesPerSecond} fps`);
        console.log(`  丢包率: ${report.packetsLost / report.packetsReceived * 100}%`);
        console.log(`  抖动: ${report.jitter} s`);
        console.log(`  码率: ${report.bytesReceived / (interval / 1000) * 8} bps`);
      }
      
      if (report.type === 'candidate-pair' && report.state === 'succeeded') {
        console.log(`当前候选者对: ${report.localCandidateId} -> ${report.remoteCandidateId}`);
        console.log(`RTT: ${report.currentRoundTripTime} s`);
      }
    });
  }, interval);
}

30.4.2 媒体流录制与回放

有些问题需要录下来慢慢分析。我推荐用 MediaRecorder 录制本地和远程流：

// 录制媒体流
function recordStream(stream, duration = 30000) {
  const recorder = new MediaRecorder(stream, {
    mimeType: 'video/webm;codecs=vp8,opus'
  });
  
  const chunks = [];
  recorder.ondataavailable = e => chunks.push(e.data);
  
  recorder.onstop = () => {
    const blob = new Blob(chunks, { type: 'video/webm' });
    const url = URL.createObjectURL(blob);
    
    // 保存到本地或上传
    downloadBlob(blob, `webrtc-recording-${Date.now()}.webm`);
  };
  
  recorder.start(1000); // 每秒生成一个 chunk
  setTimeout(() => recorder.stop(), duration);
}

录制下来的视频，可以用 Chrome 的 Media Player 逐帧分析。我习惯看三个指标：

• 帧间隔是否均匀——不均匀说明编码器或网络有问题
• 是否有花屏/绿屏——通常是丢包导致的关键帧丢失
• 音画是否同步——唇音不同步说明时间戳有问题

30.5 全链路排查实战案例

讲一个我实际遇到的案例。用户反馈“视频通话经常断连”，但没有任何报错信息。

排查过程：

1. 信令层：查看日志，发现 ICE Candidate 在连接建立后 30 秒才到达。原因是信令服务器做了消息队列，Candidate 被延迟发送了。
2. 传输层：修复信令延迟后，ICE 连接状态从 connected 变成 disconnected。检查候选者，发现 relay 候选者超时了。
3. 媒体层：最终定位到 TURN 服务器配置错误，导致 relay 候选者无法使用。修复 TURN 配置后，问题解决。

30.6 调试环境搭建清单

最后，给你一个完整的调试环境搭建清单：

组件	工具/方法	用途
信令日志	自定义中间件 + 文件日志	记录所有信令消息
SDP 分析	自定义解析器 + 表格展示	检查编解码器、ICE 参数
ICE 监控	chrome://webrtc-internals	观察 ICE 状态和候选者
网络抓包	Wireshark + RTP 过滤	分析网络层问题
媒体统计	getStats API + 可视化	监控帧率、丢包、抖动
流录制	MediaRecorder	录制问题现场

嗯，这套环境我用了两年，帮我解决了不少线上问题。你照着搭一遍，以后排查 WebRTC 问题会轻松很多。

---

公众号:蓝海资料掘金营，微信deep3321