做实时音视频这块WebRTC 是一个绕不开的东西——不管你是在做在线课堂、视频面试、远程会诊、多人会议还是只想在网页里塞一个面对面的画面最后大概率都会走到它面前。但它的入门曲线确实有点陡文档散落在各种规范里概念密度高一个典型的 Demo 往往只给你几十行代码却藏着 SDP、ICE、NAT 穿越、候选交换一大堆东西跑通了也不知道为什么通跑不通更不知道为什么不通。这篇内容面向的就是刚接触 WebRTC 的零基础同学也适合已经能把官方 Demo 跑起来、但一换网络环境就抓瞎的开发者。我会按先讲清楚它在解决什么问题—再拆开三个核心概念—然后从零搭一个一对一通话—最后把我踩过的坑和排查手法摊开这个顺序走代码可以照着抄参数可以照着调但更重要的是每一步为什么这么做。全文不涉及任何特定厂商服务示例里的服务器地址都用占位写法你换成自己的即可。1. WebRTC 的整体设计思路它到底在解决什么问题1.1 从服务器中转到点对点直连的取舍要理解 WebRTC先得理解它想干掉什么。传统的实时音视频方案基本是客户端—服务器—客户端的中转模型我采集画面编码压缩推流到一台中心服务器服务器再分发给对端。这个模型的好处是简单可控服务器知道所有人的状态做混流、录制、鉴权都很方便。坏处也很明显——所有流量都要过中心节点用户离服务器越远延迟越大服务器带宽成本随并发线性上涨一旦中心节点抖动所有人都卡。WebRTC 的核心主张是能直连就直连。两个浏览器之间如果能打通一条 UDP 通道媒体流就直接在两端跑不经过你的业务服务器。这样延迟能压到几十毫秒级别服务器只需要承担牵线搭桥的工作不扛媒体流量。这个思路决定了 WebRTC 所有设计的走向——它必须解决两个藏在各自路由器后面的设备怎么互相找到对方并建立通道这个问题而这恰好是整件事里最麻烦的部分。这里要提醒一句直连不是万能的。两个用户如果都在对称型 NAT 后面或者企业网络封了 UDP直连就是打不通这时候必须回落到中继。所以 WebRTC 的完整形态是优先直连失败中继不是永远直连。很多人第一次接触时以为 WebRTC 等于 P2P这个理解偏差会导致后面排查问题时方向跑偏。1.2 三大模块的分工采集编码、连接协商、传输通道把 WebRTC 拆开看它其实由三块相对独立的能力组成这三块在 API 层面也分得很清楚。第一块是媒体采集与处理对应getUserMedia。它负责向用户申请摄像头和麦克风权限拿到原始的音视频轨道并支持分辨率、帧率、回声消除、降噪这些约束参数。这一块本身和网络无关就算你不做通话只做本地录制或拍照预览也会用到。第二块是连接协商对应RTCPeerConnection的会话描述交换过程。这是 WebRTC 里最抽象的部分双方要互相告知我支持什么编码、我的网络地址有哪些、我用什么传输方式然后协商出一个双方都接受的方案。这套信息用 SDP 这种文本格式承载通过你自己实现的信令通道来回传递。第三块是数据传输也是RTCPeerConnection的一部分但方向不同——音视频走 MediaStream 轨道任意数据走RTCDataChannel。数据通道底层用的是 SCTP over DTLS支持可靠有序、可靠无序、部分可靠等多种模式做文件传输、文字聊天、游戏状态同步都能用。这三块的边界很重要采集失败和协商失败是完全不同的两类故障前者通常表现为没有画面但连接状态正常后者表现为连接一直卡在某个状态。分清楚在排查时能省下大量时间。1.3 为什么它不负责信令——这个设计留下的坑WebRTC 规范里刻意没有定义信令协议。也就是说双方怎么把 SDP 和 ICE 候选传给对方规范不管你得自己解决。可以走 WebSocket可以走 HTTP 轮询甚至可以复制粘贴文本手动传很多人第一次调试就是这么干的。这个设计当初是为了保持中立让 WebRTC 能适配各种既有架构。但落到实际开发上它意味着你至少要多写一个信令服务。这不是可选项是必需项。我见过不少人拿着 Demo 代码改发现两个浏览器在同一台机器上能通、换台机器就不通最后发现是 Demo 里把 SDP 直接写在同一个页面的变量里根本没有跨设备的传递通道。还有一个衍生问题信令服务要维护房间和用户的概念要处理用户上下线、重连、并发加入这些状态。这些在 WebRTC 规范里全是空白得自己在业务层实现。所以一个能上线的一对一通话代码量通常是这样分布的媒体相关 20%协商相关 30%信令和房间管理 50%。新手往往低估了最后这块。2. 动手前必须搞懂的三个核心概念2.1 SDP一份用文本写成的能力清单SDPSession Description Protocol第一次看到会觉得像天书一堆m、a、c开头的行。但它的本质非常朴素就是一份文本格式的能力清单描述我这边有哪些媒体流、用什么编码、走哪个地址和端口、支持哪些扩展。一份典型的 offer SDP 里有这几类关键信息maudio和mvideo行声明有几路媒体artpmap说明每个 payload type 对应什么编码比如 opus、VP8、H264aice-ufrag和aice-pwd是本次会话的认证凭据afingerprint是 DTLS 证书指纹用于加密握手校验c行和acandidate行给出网络地址。看 SDP 有个技巧先只看m行数清有几路媒体再看每路下面的artpmap确认编码最后看asetup确认谁是 DTLS 主动方。这三件事搞清楚剩下的细节可以等出问题时再查。我调试时习惯把 SDP 打印到控制台后按m分段折叠不然一行行读太痛苦。关于协商流程有个容易混淆的点offer/answer 模型里发起方调createOffer生成 offer设为自己的本地描述发给对方接收方调setRemoteDescription应用 offer再createAnswer生成 answer设为本地描述发回发起方收到 answer 后setRemoteDescription。四步一步都不能少顺序也不能乱。乱序的典型症状是控制台报InvalidStateError或者连接状态一直停在new。2.2 ICE 候选与 NAT 穿越为什么需要 STUN 和 TURNICEInteractive Connectivity Establishment解决的是我有哪些地址可以被对方连到。一个设备可能同时拥有局域网地址192.168.x.x、公网映射地址、中继地址每一种都是一个候选candidate。双方把各自所有候选都发给对方然后两两配对尝试连通哪对先通就用哪对。候选分三类优先级从高到低host是本机地址同一局域网内最快srflx是通过 STUN 服务器探测到的公网映射地址跨公网直连时用relay是通过 TURN 服务器分配的中继地址直连失败时的兜底。STUN 的作用很轻量客户端发一个请求给 STUN 服务器服务器把我看到你的源地址是 X:X回给你。就这一件事。它能帮你发现自己被 NAT 映射成什么样但帮不了你打通对称型 NAT。TURN 就重多了它是一台中继服务器双方都把媒体流发给它它再转发。这意味着它要承担全部带宽成本。我一般会在项目初期就把 TURN 部署好哪怕直连成功率有 85%剩下 15% 的用户如果不给兜底就是直接不可用。真实网络环境里企业网络、移动网络、部分公共网络的 NAT 类型非常复杂对称型 NAT 的比例远比实验室环境高。ICE 还有个细节值得说候选收集是异步的onicecandidate会陆陆续续触发多次最后以null结束表示收集完毕。很多人只在第一次回调时发送候选导致后面的候选丢失表现就是有时候能通有时候不能通。正确做法是每次回调只要有候选就发给对方或者等icegatheringstate变成complete后一次性发完整 SDP。2.3 信令通道自己搭的那座桥前面说了 WebRTC 不管信令那具体要传什么至少三类消息offer/answer 的 SDP、ICE 候选、控制信令比如挂断、静音、重新协商。如果做多人还要加房间加入、成员列表同步。信令通道的技术选型上WebSocket 是最常见的因为它是全双工、延迟低、浏览器原生支持。HTTP 轮询也能用但延迟和开销都差一些。选型时要注意两个点一是消息顺序SDP 必须在候选之前或同时到达乱序会导致候选匹配失败二是断线重连网络抖动后信令断了WebRTC 的媒体通道可能还活着这时候要不要重建整个会话需要明确的策略。我在实现信令时踩过一个坑把候选消息和 SDP 消息放在同一个队列里但没做序号标记服务端因为并发处理导致候选先于 SDP 到达对端接收方在还没设置远程描述的情况下收到候选直接丢弃结果连接一直卡在checking。后来给每条消息加了单调递增的序号接收端做缓冲排序问题消失。这个细节在任何教程里都不会写但实际项目中很常见。3. 从零跑通一个一对一音视频通话3.1 环境准备与最小页面骨架先说环境。WebRTC 的很多能力受浏览器安全策略限制必须在 HTTPS 或 localhost 下才能调用getUserMedia。局域网内用 IP 直接访问会拿不到权限控制台报NotAllowedError或者干脆navigator.mediaDevices是 undefined。本地开发用localhost没问题要真机测试就得配证书这是新手最容易卡住的第一关。页面骨架不需要任何框架一个视频容器加几个按钮就够了div video idlocalVideo autoplay muted playsinline/video video idremoteVideo autoplay playsinline/video /div button idstartBtn开始/button button idcallBtn呼叫/button button idhangupBtn挂断/button两个属性必须写本地视频要加muted否则自己的声音会回放形成啸叫两个视频都要加playsinline不然在移动端会自动全屏播放体验很糟。这两点看着小实际调试时能省掉很多为什么有回声为什么iOS上画面跳走了的困惑。3.2 采集本地流与媒体约束参数采集这一步的代码很短但参数很有讲究const constraints { audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }, video: { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30, max: 30 }, facingMode: user } }; const localStream await navigator.mediaDevices.getUserMedia(constraints); document.getElementById(localVideo).srcObject localStream;这里用的是ideal而不是精确值意思是尽量满足满足不了给个接近的。如果用精确值设备不支持就直接报OverconstrainedError用户看到的就是一个错误弹窗。实际项目中我建议全部用ideal再用getSettings()读回实际生效的参数做日志方便判断问题。音频那三个开关默认是开的但显式写出来有好处一是明确意图二是某些浏览器在特定组合下行为不一致写清楚便于排查。facingMode: user指定前置摄像头移动端做自拍类应用时需要桌面端会被忽略。还有一个常被忽略的操作页面关闭或挂断时要把轨道停掉。stream.getTracks().forEach(t t.stop())不停的话摄像头指示灯会一直亮着用户会以为你在偷拍。这个细节在演示时特别影响观感。3.3 建立连接与交换 SDP 的完整流程RTCPeerConnection的构造参数里最关键的是iceServersconst pc new RTCPeerConnection({ iceServers: [ { urls: stun:your-stun-host:3478 }, { urls: turn:your-turn-host:3478, username: your-user, credential: your-credential } ], iceTransportPolicy: all, bundlePolicy: max-bundle });stun:和turn:后面的地址换成你自己的服务即可。bundlePolicy: max-bundle的意思是尽量把所有媒体复用到同一条传输通道上减少端口占用和握手开销这个选项在现代浏览器上基本是默认推荐。把本地轨道加进连接localStream.getTracks().forEach(track { pc.addTrack(track, localStream); });注意要用addTrack而不是老式的addStream后者已经废弃。addTrack的第二个参数是 stream 引用作用是让对端在ontrack事件里能拿到轨道归属的流对象方便直接把整个流赋给 video 元素。发起方生成 offer 的流程async function createOffer() { const offer await pc.createOffer(); await pc.setLocalDescription(offer); sendSignal({ type: offer, sdp: pc.localDescription }); }这里有个细节setLocalDescription之后要发的是pc.localDescription而不是原始的offer对象。因为浏览器可能会在设置本地描述时修改 SDP比如补充 ICE 凭据、调整编码顺序直接发原始 offer 在某些浏览器上会导致对端解析异常。接收方处理async function handleOffer(sdp) { await pc.setRemoteDescription(new RTCSessionDescription(sdp)); const answer await pc.createAnswer(); await pc.setLocalDescription(answer); sendSignal({ type: answer, sdp: pc.localDescription }); }接收方在setRemoteDescription之后要立刻把ontrack事件挂上否则可能错过轨道到达的通知。稳妥的做法是在创建pc之后就注册所有事件监听别等到处理 offer 时才挂。3.4 ICE 候选交换与连接状态监听候选交换的代码就三行但位置很关键pc.onicecandidate (event) { if (event.candidate) { sendSignal({ type: candidate, candidate: event.candidate }); } }; // 收到对端候选时 async function handleCandidate(candidate) { if (pc.remoteDescription) { await pc.addIceCandidate(new RTCIceCandidate(candidate)); } else { pendingCandidates.push(candidate); } }那个pendingCandidates队列就是前面提到的排序缓冲。候选可能在远程描述设置之前到达这时候不能直接丢要存起来等描述设置完再统一加。我第一版代码就是直接丢结果在同一局域网测试时因为延迟低没暴露一换到公网就间歇性失败排查了很久。状态监听我一般挂两个pc.onconnectionstatechange () { console.log(connection:, pc.connectionState); }; pc.oniceconnectionstatechange () { console.log(ice:, pc.iceConnectionState); };iceConnectionState反映的是网络层连通性取值有checking、connected、completed、failed、disconnected。connectionState是更高层的聚合状态包含 DTLS 握手结果。排查时两个都看如果 ice 到了connected但 connection 还是connecting说明网络通了但加密握手有问题通常是证书指纹不匹配或者时钟偏差如果 ice 一直checking然后转failed那是候选配对全失败去查 STUN/TURN 配置和防火墙。3.5 完整串联与实测结果把上面的片段串起来一个最小可用的一对一通话大约 120 行代码。我实测的环境组合是同一局域网两台机器、一台在移动网络一台在办公网、以及两端都在企业网内。结果如下测试场景直连结果建立耗时说明同一局域网host 候选直连成功约 0.2 秒最快几乎无感知一方移动网络一方宽带srflx 直连成功约 1.2 秒需要 STUN 探测公网地址两端都在严格企业网直连失败TURN 中继兜底约 2.5 秒走中继延迟增加 30-60ms一方网络抖动先 disconnected 后恢复恢复约 3 秒ICE 重启机制生效720p 30 帧的实际码率在 1.2-2.2 Mbps 之间浮动取决于画面复杂度。这个数字可以这样估算1280×720 像素每像素假设压缩后平均 1.2 比特一帧约 1.1 Mbit乘以 30 帧理论上很大但因为帧间压缩只传变化部分实际码率能压到两兆以内。做带宽规划时一对一按 3 Mbps 预留比较稳妥多人场景要乘上每个人的上行路数。4. 常见问题与排查技巧实录4.1 黑屏、无声、只有单向画面的排查顺序这三类症状看着相似根因完全不同我整理了一个固定的排查顺序能覆盖九成情况。第一步看连接状态。如果connectionState不是connected那根本还没到媒体层别去看视频元素先解决连通性。如果已经connected但没画面才进入下一步。第二步看ontrack有没有触发。在事件里打印event.track.kind和event.streams.length。没触发说明对端压根没加轨道或者加了但没在 SDP 里体现——去检查对端是不是忘了addTrack或者addTrack之后没有重新协商。第三步看视频元素的srcObject和属性。黑屏最常见的原因是远程流赋给了元素但元素被display: none了或者元素尺寸为 0。还有一种情况是本地流被muted影响到了远程元素虽然不常见但确实遇到过两个 video 的 id 写反了。无声的排查多一步音频轨道到达了但没声音先确认不是自动播放策略拦截。浏览器要求用户交互后才能播放有声音的媒体如果页面加载就自动建立连接远程音频会被静音。解决办法是在用户点击时调一次video.play()或者给元素加autoplay配合用户手势触发。只有单向画面通常是其中一方的上行带宽不足或者编码不兼容。用pc.getStats()看outbound-rtp的bytesSent是否在增长不增长说明卡在编码或发送环节再对比双方的 SDP 里artpmap的编码列表如果没有交集协商会失败但某些情况下不报错只是没画面。4.2 连接一直卡在 checking 或 failed 的处理这是最高频的问题八成出在网络配置上。按这个顺序查先确认iceServers里的地址真的可达。用一个简单的方式验证在浏览器里直接请求 STUN 服务或者跑一个独立的连通性检测工具看能不能拿到 srflx 候选。拿不到就是服务地址、端口、协议写错了或者服务本身没起。再确认 TURN 的用户名密码。TURN 是带认证的凭据错误时服务端会静默丢弃请求客户端表现就是只有 host 候选、没有 relay 候选。判断方法很简单看pc.onicecandidate收到的候选里candidate.type有没有relay没有就是 TURN 没生效。然后查防火墙和 UDP。企业网络经常封 UDP 高端口WebRTC 会在 49152-65535 范围内随机选端口。如果 UDP 全封只能走 TCP 中继需要在 TURN 配置里显式指定transport: tcp同时确保服务端开了 TCP 监听。最后看 NAT 类型。两端都是对称型 NAT 时srflx 候选匹配必然失败只能靠 relay。如果这时候 TURN 又没配好就是死局。这种情况的日志特征是候选收集完整配对尝试全部超时然后failed。还有一个隐蔽的坑时间不同步。DTLS 握手依赖证书和时间戳两端系统时间差超过几分钟就会握手失败表现是 iceconnected但 connection 卡在connecting。这个在企业内网虚拟机上很常见同步一下时间就好。4.3 带宽、分辨率与码率的参数怎么定参数调优没有标准答案但有个推导思路。先确定目标你要的是清晰度还是流畅度在线课堂偏清晰能看清板书视频通话偏流畅表情自然远程操控偏低延迟。清晰度优先的场景分辨率给到 1280×720帧率 15-20 就够帧率低一点能省不少码率因为帧间差异变小。流畅度优先的降到 640×480 或 960×540帧率拉到 30。低延迟场景分辨率 640×360、帧率 24、开启degradationPreference: maintain-framerate。码率的上限可以用setParameters控制const sender pc.getSenders().find(s s.track.kind video); const params sender.getParameters(); params.encodings[0].maxBitrate 1500000; // 1.5 Mbps params.encodings[0].maxFramerate 24; await sender.setParameters(params);注意getParameters()返回的encodings数组在某些浏览器上初始为空直接访问[0]会报错。稳妥写法是先判断为空就手动塞一个对象进去再setParameters。这个坑我在两个不同内核的浏览器上都遇到过行为还不一致。还有一个动态调整的手法监听getStats()里的availableOutgoingBitrate当它下降到当前码率的 80% 以下时主动降档。这个逻辑写起来不复杂但对弱网体验改善很明显。4.4 常见问题速查表现象最可能原因快速验证处理方式拿不到摄像头权限非 HTTPS 环境看navigator.mediaDevices是否存在配证书或用 localhost有画面没声音自动播放策略拦截手动点击页面后是否有声用户手势触发play()连接一直 checkingSTUN 不可达候选里无 srflx检查地址端口协议只有 host 候选TURN 凭据错误候选里无 relay核对用户名密码连接 connected 但无画面未触发ontrack打印事件日志检查对端addTrack间歇性连不上候选丢失或乱序对比前后 SDP 候选数加候选缓冲队列几秒后断开网络切换或 ICE 超时看iceConnectionState变化实现 ICE 重启回声严重本地流未静音检查 video 元素属性加muted这张表我贴在项目文档首页新人遇到问题先自查一遍能过滤掉大部分低级问题。5. 再往前走一步数据通道、多人模型与上线准备5.1 RTCDataChannel被低估的那半边能力很多人把 WebRTC 等同于音视频其实RTCDataChannel是另一条完全独立的能力线。它建立在 SCTP 之上支持配置可靠性和顺序性const dc pc.createDataChannel(chat, { ordered: true, maxRetransmits: 3 }); dc.onopen () dc.send(hello); dc.onmessage (e) console.log(e.data);ordered: true保证消息按序到达maxRetransmits限制重传次数超过就丢弃。这两个参数组合出四种模式可靠有序类似 TCP、可靠无序、部分可靠有序、部分不可靠类似 UDP。做文件传输用可靠有序做实时位置同步用部分不可靠——丢一两帧位置无所谓卡住等重传反而更糟。数据通道和媒体通道共享同一条 ICE 连接意味着建立连接的成本是复用的。我做过一个场景先建立通话通话过程中通过数据通道传文件和共享白板不需要额外建连体验很顺。这个组合在实际项目里价值很高但很多教程只讲音视频把这半边浪费了。要注意的是数据通道的单条消息大小限制。虽然规范允许较大消息但实际各浏览器实现有差异超过 16KB 建议自己分片。分片逻辑要带序号和总片数接收端拼装后再交付业务层。5.2 多人场景Mesh、SFU 怎么选一对一跑通之后下一步通常是能不能三个人一起。这时候架构选择就摆上台面了。Mesh网状是最简单的每个人都和其他所有人建一条连接。三个人就是三条连接每个人要编码上传两份。优点是无需媒体服务器成本极低缺点是上行带宽随人数线性增长五个人以上基本不可用。适合三五人的小会议、临时沟通。SFU选择性转发是主流方案每个人只和服务器建一条连接上传一份服务器根据订阅关系转发给其他人。上行压力恒定扩展性好能做到几十人。代价是要维护媒体服务器运维复杂度上升。市面上有若干开源实现可以自建具体选型要看你的并发规模和功能需求是否需要录制、混流、转码。MCU混流是把所有画面在服务器端合成一路再下发客户端压力最小但服务器 CPU 开销大且灵活性差用户不能单独调整某个人的布局。现在用得比较少了除非是特殊场景比如直播连麦。我的建议是先用 Mesh 把业务跑通验证需求人数上限超过 6 人就该考虑 SFU。不要一上来就上 SFU运维成本会把小团队拖垮。多人场景还有一个绕不开的问题重新协商。有人加入或离开时SDP 要重新交换这时候已有的连接要不要断Mesh 下每个人和新加入者建新连接即可老的不用动SFU 下通常是服务器通知客户端调整订阅不重建连接。这块的状态管理很琐碎建议一开始就把房间状态和连接状态分开建模别混在一起。5.3 上线前必须确认的几件事从 Demo 到上线有几件事必须补齐缺一件都可能出事故。第一TURN 必须有。前面反复说了这里再强调一次没有 TURN 的 WebRTC 应用在真实网络里的可用率大概只有八成多。剩下的一成多用户就是完全不可用而且你从日志里看不出原因因为他们的失败发生在网络层。TURN 服务器的带宽要按最坏情况全走中继来预留虽然实际用不到那么多但计费模型要按这个量级设计。第二权限和降级要有兜底。用户拒绝摄像头权限、设备没有麦克风、浏览器版本太老这些都要有明确的提示和降级路径。纯音频通话、文字替代方案都比一个白屏错误页好。第三日志要打全。至少记录SDP 全文、候选列表及类型、连接状态变迁序列、getStats()的关键指标码率、丢包率、往返时延。出问题时这些是唯一线索。我习惯在连接失败时自动把这几项打包上报事后分析效率高很多。第四注意自动播放和页面可见性。页面切到后台时浏览器会降低定时器频率和渲染优先级视频可能卡顿。如果业务要求后台继续通话需要处理visibilitychange必要时用音频上下文维持活跃状态。第五测试要覆盖弱网。用开发者工具的网络限速能模拟带宽但模拟不了丢包和抖动。有条件的话用专门的弱网模拟工具把丢包率设到 5%、10%观察 ICE 恢复和码率自适应是否正常工作。这一步能提前发现大量线上问题。我个人在实际项目里的体会是WebRTC 的学习曲线陡峭不是因为 API 复杂恰恰相反它的 API 设计得相当克制。真正难的是它把网络世界的复杂性赤裸裸地摆到了你面前——NAT、防火墙、带宽波动、设备差异这些问题在传统中转方案里被服务器掩盖了直连方案里全部暴露。所以我的建议是先把一对一在三种网络环境下都跑稳再去碰多人先把连通性排查链路摸熟再去调画质参数。顺序反了会在细节里陷很久。最后分享一个小技巧调试时在页面上加一个隐藏面板实时显示iceConnectionState、当前选中的候选对类型host / srflx / relay、上下行码率和丢包率。这个面板在演示时藏起来出问题时按快捷键呼出。它比翻控制台快得多尤其是在用户现场排查时一眼就能看出是走了中继还是直连。
