简介这套支持WebRTC的SIP JS演示项目利用JSSIP库在浏览器中完成音视频通话与即时消息面向前端开发者、实时通信初学者以及需要快速验证SIP信令流程的实验人员。压缩包共72个文件大小3.16MB包含可直接打开的HTML页面、负责交互与控制逻辑的JavaScript脚本、用于布局的CSS样式以及OGG/WAV格式的来电去话提示音、PNG/JPG/GIF格式的拨号盘与状态图标等UI素材并附有README说明整体结构清晰。示例覆盖从SIP注册、发起呼叫、接听应答、媒体流建立到挂断回收的完整流程同时演示了初始化UA、监听注册与来电事件、调用invite发起对话、绑定远端音频流、处理错误等关键代码路径可以直接在本地运行体验也可以作为二次开发脚手架继续扩展。目前已有771人学习下载适合借助该示例边看边练逐步掌握WebRTC与SIP结合的实时通信开发思路。1. 支持WebRTC的SIP.js Demo到底在解决什么问题如果你做过WebRTC点对点通话你大概率遇到过同一个尴尬两个浏览器直连很容易跑通但一旦要和传统话机、软交换、呼叫中心打通WebRTC的“纯P2P”能力就显得很不够看。这个时候通话需要的不只是媒体通道还需要一个信令通道——谁来注册、谁来鉴权、怎么寻址、如何路由。支持WebRTC的SIP.js Demo就是一套能在浏览器里直接用JavaScript实现SIP注册和呼叫的参考实现SIP消息通过WebSocket收发媒体流通过WebRTC传输业务层完全走HTTP和JS事件回调。它能解决的是“浏览器作为SIP终端”这件事让网页变成一个可注册、可拨打、可被呼叫的电话端点。适合三类人去读一是刚接触VoIP的前端工程师想快速理解SIP和WebRTC怎么配合二是做呼叫中心或软电话产品的开发者需要一个不依赖插件的浏览器端方案三是运维兼开发的人想评估这套链路在生产环境里的坑。下面从选型、搭环境、写代码到排障把这条链路完整走一遍。2. 先把方案立住SIP over WebSocket与浏览器通话的技术选型2.1 SIP.js为什么是WebRTC通话的主流选择浏览器里做SIP接入绕不开的一个问题是SIP协议跑在UDP/TCP上而浏览器只能发WebSocket和HTTP请求。纯WebRTC又只解决媒体传输和加密不负责“谁是用户”“如何呼叫他人”这些信令问题。所以标准的做法是SIP服务器开放WebSocket端口SIP消息封装在WebSocket帧里媒体走RTP但由WebRTC接管这样浏览器就同时拿到了SIP的寻址能力和WebRTC的音视频能力。在JavaScript生态里SIP.js是这条链路最主流的实现库。它不是把整个SIP协议栈塞进浏览器而是在WebSocket层实现了注册、鉴权、呼叫发起、挂断等基本事务同时把媒体协商部分委托给浏览器的RTCPeerConnection。这样做的好处很明显你不需要自己解析SDP、维护事务状态机、处理鉴权重传这些SIP.js内部都做了。遇到特殊需求比如要改SDP里的编解码优先级SIP.js也提供了钩子去操作底层会话描述处理器。选型时还有一个常见方案是直接用WebRTC的DataChannel自定义信令但这条路只适合两家都是自家客户端的场景。只要对端是标准话机、SIP网关或运营商线路你就必须用SIP。所以“SIP.js WebRTC”不是二选一而是各管一段。我这里说的Demo默认技术栈是SIP.js负责信令与注册WebRTC负责媒体WebSocket负责SIP消息的传输承载。2.2 跑通Demo前必须搭好的SIP服务器与WebSocket网关有了SIP.js浏览器端就只剩一个前端页面但信令总得有个去处。常见做法是部署一个开源SIP服务器开启WebSocket监听和WebRTC网关支持。很多人在这一步就卡住SIP服务器默认只监听UDP 5060没有打开WS端口结果浏览器一直报连接失败。我的习惯是先用一台内网服务器做验证配置大致是一个SIP域一个WebSocket端口一组用于注册的账号以及一个用于测试互通的电话分机。WebSocket监听端口常见用的是5060、5061、8089、8443这几个其中8089和8443经常被用于代理层入口如果你的环境前面有Nginx则建议直接把WSS终结在Nginx再反代到SIP服务器的WS端口这样证书管理更顺。需要说明的是浏览器对“不安全”的WebSocket是拒绝连接的。如果页面是HTTP协议SIP.js连接时只能用ws://如果页面是HTTPS则必须使用wss://且证书有效。混用是新手最常见的启动失败原因。我在本地调试时页面用本地HTTP服务SIP服务器用内网ws://192.168.x.x:8089这样能避开证书问题一旦要上生产或测试环境就整体切换到带有效证书的wss://这一步不要偷懒。2.3 最小环境清单与参数约定跑通这个Demo我们只需要四条链路的配合浏览器页面、SIP.js、WebSocket网关、SIP服务器。参数约定如下提示以下参数是Demo环境的约定值不是标准。实际部署按你的SIP服务器配置来改。SIP域/服务器内网IP或DNS名端口按实际配置WebSocket地址ws://内网IP:8089/ws部分服务器要求路径带/ws分机账号例如1001密码由服务器设置或由管理员分配呼叫对端可以是另一个浏览器注册的分机也可以是软交换下的其它SIP终端这套环境只要起来了后面调代码就快。如果服务器没配好SIP.js注册阶段就会明显报错错误通常是Connection Closed或WebSocket disconnected这类报错80%不是代码问题而是服务器端WS没监听成功。先去服务器上看端口有没有起来再做前端排查。3. 跑通注册与拨打用SIP.js写的第一个浏览器电话Demo3.1 页面与UA初始化从拿到账号到注册上线写Demo的第一步先起一个最小页面。我用Vite搭一个HTML页样式极简只放两样东西一个显示给对方的本地摄像头预览区域一个显示通话中对方画面的区域。实际操作中不需要一开始把界面做复杂能跑通注册和呼叫这一阶段的目标就完成了。接下来是UA初始化和注册。下面的代码是SIP.js 0.20.x这条技术线的常见写法同时兼容了后续版本的基础API。需要说明这条版本线中SIP.UA是构造入口后续新版本改成SIP.UserAgent但核心概念一致。import SIP from sip.js; // UA参数 const ua new SIP.UA({ uri: sip:1001192.168.1.10, authorizationUsername: 1001, authorizationPassword: 123456, transportOptions: { server: ws://192.168.1.10:8089/ws, }, // 注册与重连策略 register: true, registerExpires: 120, // WebRTC媒体回调 sessionDescriptionHandlerFactory: SIP.Web.SessionDescriptionHandler.defaultFactory, }); ua.on(registered, () { console.log(注册成功); }); ua.on(unregistered, () { console.log(注销或注册失败); }); ua.on(disconnected, () { console.log(WebSocket断开等待重连); }); ua.start();这段代码的核心是SIP.UA的构造参数uri决定这个UA在SIP世界里的身份格式是用户域这里的域一般要和SIP服务器配置的SIP域一致而不是随便写authorizationUsername和authorizationPassword用于鉴权很多服务器用的是Digest鉴权SIP.js在收到401后会自动带着摘要再注册一次不需要你手工处理。transportOptions.server就是WebSocket网关地址路径是否带/ws取决于服务器的WS监听配置。registerExpires设成120秒表示每两分钟刷新一次注册太短会增加服务器压力太长则有些服务器会主动踢掉经验值是90到300秒之间。逻辑上的关键点是ua.start()要放在事件绑定之后否则可能错过registered事件。很多新人习惯先把start()写在前面最后才加事件结果注册成功了却看不到回调误以为自己代码写错了。实际是事件已经触发了只是当时没人监听。3.2 拨打与接听Session的发起、应答与挂断注册成功后拨号就是一个ua.call的过程。这里会拿到一个Session对象之后所有通话状态都通过它的方法去控制比如accept、terminate。下面是一段完整的拨号与接听代码我把它拆成一个callButton触发打电话、answerButton触发接听的最小实现。let currentSession null; // 拨号按钮呼叫分机1002 document.getElementById(callBtn).onclick () { const target sip:1002192.168.1.10; currentSession ua.call(target, { // 发起呼叫时指定媒体方向 sessionDescriptionHandlerOptions: { constraints: { audio: true, video: true, }, }, }); currentSession.on(remoteVideoAdded, () { // 远端画面加入 const remoteVideo document.getElementById(remoteVideo); remoteVideo.srcObject currentSession.remoteMediaStream; remoteVideo.play(); }); currentSession.on(bye, () { console.log(对方挂断); closeMedia(); }); }; // 接听按钮 document.getElementById(answerBtn).onclick () { if (currentSession) { currentSession.accept({ sessionDescriptionHandlerOptions: { constraints: { audio: true, video: true }, }, }); console.log(已接听); } }; // 挂断按钮 document.getElementById(hangupBtn).onclick () { if (currentSession) { currentSession.terminate(); closeMedia(); } };这里的ua.call(target, options)第一个参数是B方的SIP URI第二个参数是会话选项。constraints直接映射到getUserMedia的参数audio: true, video: true表示同时协商音频和视频。如果只做音频电话把video去掉或设false即可既能减轻排队时间也能减少初次协商失败的变量。需要注意接听时的accept逻辑SIP.js在收到来电时会触发invite事件但默认情况下并没有界面自动应答。Demo里把answerBtn的点击绑定到currentSession.accept()属于手动接听适合测试真实电话场景需要改造成“收到invite时弹窗确认”或“自动接听”到时把这段逻辑挪到事件回调里去就行。还需要补充一个关键点currentSession是异步建立的remoteVideoAdded是媒体协商完成后的回调。很多没跑通的人都把remoteVideo.srcObject直接写在call()返回后立刻执行此时媒体还没有准备好拿到的remoteMediaStream是空对象结果必然黑屏。正确做法就是像我上面这样在事件回调里做绑定。3.3 用事件回调把通话状态同步到界面SIP信令是状态性的注册、拨号、振铃、接通、挂断各有各的事件。把状态同步到界面是Demo从“控制台能看日志”走到“界面能用”的关键一步。SIP.js里有几个高频事件我把它们列成对照关系。事件触发时机界面建议registered注册成功显示在线状态unregistered注销成功或失败显示离线状态disconnectedWebSocket断开显示断线重连中invite收到来电弹出接听/拒接按钮remoteVideoAdded远端媒体就绪绑定video画面localVideoAdded本地媒体就绪绑定本地预览bye对方挂断清除通话界面refer收到呼叫转移请求根据业务决定是否跟随这个映射表重点解决“状态机混沌”的问题。我见过不少开发者界面上只有一个isCalling布尔值各种误会和错乱来电、呼出、挂断互相覆盖。正确做法是用一个枚举值管理通话状态idle、registering、ringing、inCall、terminated。每次事件更新状态值再由统一渲染函数更新UI不要在每个回调里都动DOM。比方说invite这个事件脚本里是用ua.on(invite, session ...)挂监听收到后先把currentSession指向这个传入的session再把界面切到“来电振铃”状态。如果当前已经在通话中还需要加个判断要么拒绝要么按业务逻辑把新来电挂掉或转入等待。这些都属于真实产品里的细节Demo阶段可以先不做但事件结构最好从一开始就按这个层级去组织后面扩展不伤筋动骨。4. 音视频与媒体协商从能通到能用的关键参数4.1 localVideo与remoteVideo的绑定时机注册和呼叫刚跑通时画面常常是黑的这几乎成了每个首次接触SIP.js开发者的“玄学一夜”。其实问题不复杂本地视频要等getUserMedia成功后才会有流远端视频要等SDP协商完成、ICE候选配对成功后才有帧。两者都有精确的事件时机。本地视频的绑定要放在ua.call传入的sessionDescriptionHandlerOptions.constraints生效之后也就是本地媒体加载完成那个回调上。SIP.js的这个回调名是localVideoAdded但部分版本需要在会话描述处理器的参数里开启本地预览才触发import SIP from sip.js; // 自定义会话描述处理器参数 const sdhOptions { constraints: { audio: true, video: { width: { ideal: 1280 }, height: { ideal: 720 }, }, }, // 启用本地预览 localVideo: document.getElementById(localVideo), }; currentSession ua.call(sip:1002192.168.1.10, { sessionDescriptionHandlerOptions: sdhOptions, }); currentSession.on(localVideoAdded, () { // 此时可确保localVideo已经拿到媒体流 console.log(本地预览已启动); });注意这里用了宽高约束。width和height设置ideal值时浏览器会在不改变摄像头能力的前提下尽量接近这个分辨率不用mandatory是因为有些设备或浏览器不支持强制分辨率时会导致采集直接失败。localVideo如果指向页面里的video元素SIP.js会自动把流注入进去不需要再手动写srcObject如果某些版本没自动注入就在localVideoAdded回调里补上localVideo.srcObject event.stream。远端视频的绑定发生在remoteVideoAdded但这里有一个易踩坑的点remoteMediaStream是SIP.js维护的一个组合流它会在媒体协商过程中动态加入音轨或视频轨。最好在拿到流之后设置remoteVideo.srcObject然后监听track事件的onended来做画面清理。否则对方挂断后最后一道画面可能残留在界面上让用户误以为还通着。4.2 编解码优先级与audioConstraints的设置很多人打电话通了但音质差、回声大、对方听不清。这往往不是网络问题而是没有设置音频编解码偏好和采集约束。WebRTC的强制编解码是Opus大多数SIP服务器和网关也支持G.711PCMU/PCMA。如果你的企业对端是老式网关只支持PCMU那么浏览器默认的Opus协商不出来就会导致没有声音。SIP.js暴露了audioCodecPreferences参数可以直接控制协商时优先使用哪些编解码。常见做法是优先Opus其次PCMU再考虑PCMAconst ua new SIP.UA({ uri: sip:1001192.168.1.10, authorizationUsername: 1001, authorizationPassword: 123456, transportOptions: { server: ws://192.168.1.10:8089/ws, }, register: true, // 音频编解码优先级SIP.js会优先匹配服务器支持的 audioCodecPreferences: [Opus, PCMU, PCMA], // 音频采集约束单声道、16k采样率适合通话场景 audioConstraints: { channelCount: 1, sampleRate: 16000, }, });audioCodecPreferences的解析逻辑是按照你给的顺序在SDP协商时优先选择第一个两边都支持的编码。如果服务器只支持PCMU而你把Opus放在最前面协商时会自动退到PCMU前提是服务器也允许这个编码。这个参数不用多排错时先确认服务器端支持的编码再回来对齐顺序。audioConstraints里的sampleRate: 16000和channelCount: 1对应的就是Opus在WebRTC里的典型通话配置。如果你不做设置浏览器默认的采集参数是48kHz双声道虽然音质更好但在弱网下带宽消耗更大而且对端如果是旧网关处理48kHz可能产生明显杂音。设置成16kHz单声道和人声通话频段匹配码率更低也更容易兼容。这算是我个人的偏好配置不是绝对标准你可以按实际设备调整。4.3 通话中的媒体排障看Stats和看日志电话通了但卡顿、马赛克、音频断续这类问题用“听着像网络不行”去描述是没办法定位的。正确的做法是打开浏览器内置的getStats()把关键指标拉出来看。SIP.js的Session对象上有getStats()方法它会返回RTCPeerConnection的统计数据。// 在通话中调用用于调试 if (currentSession) { currentSession.getStats().then((stats) { let audioLevel 0; let packetsLost 0; stats.forEach((report) { if (report.type inbound-rtp report.kind audio) { packetsLost report.packetsLost || 0; audioLevel report.audioLevel || 0; } if (report.type remote-inbound-rtp) { console.log(远端丢包率:, report.packetsLost); } }); console.log(本端音强:, audioLevel, 本端丢包:, packetsLost); }); }getStats()返回的不是一个数组而是一个RTCStatsReport对象所以要用forEach或for...of去遍历。inbound-rtp表示本地收到的媒体流统计remote-inbound-rtp表示远端报过来的接收统计。如果packetsLost持续增长说明链路丢包如果audioLevel常年为0说明本地麦克风采集或者发送通道有问题。日志方面SIP.js本身带有Trace级别的日志但默认不打印。在UA实例上开启日志捕获能让你在控制台直接看到完整的SIP消息和SDP协商内容ua.on(trace, (ctx) { if (ctx.type wss) { console.log([WSS], ctx.message); } if (ctx.type sip) { console.log([SIP], ctx.message); } });这里的trace事件会把底层WebSocket收发和SIP消息明文吐出来。排查问题时第一步要看SIP消息是否正常到达第二步看SDP里的maudio行和artpmap是否双方对齐。这些信息在黑匣子里是定位不了的但通过trace和getStats可以快速缩小范围。你把这个习惯养成了后续遇到再多媒体问题也能先排除信令层和编解码层的嫌疑。5. 避坑笔记SIP.js WebRTC 常见的5个翻车点5.1 注册成功却无声音现象控制台显示已注册拨通后双方都在线但完全听不到声音。原因最常见是媒体协商里只走了音频但远端没有加载出音轨或者浏览器自动播放策略拦截了audio元素。解决在remoteVideoAdded和localVideoAdded回调里检查stream.getAudioTracks().length是否为0同时确认audio元素带autoplay属性且没有被浏览器静音策略限制。我在某次测试里就是因为页面play()调用被浏览器打断导致只有画面没有声音给audio元素加mutedfalse并主动触发一次play()后问题才消失。这是个很典型的“播放器策略”而非“信令错误”的坑。5.2 拨通后单向声音现象A能听到BB听不到A。原因这种情况大多数是ICE候选没有完全交换或者STUN配置错误导致一侧无法打通音视频通道。解决先看两端是否都处于connected状态然后打开getStats()查看googCandidatePair或candidate-pair的状态如果一直停留在checking那就是UDP不通。我一般会先在UA的transportOptions里加上iceServers配置一个公网STUN服务并检查服务器是否允许UDP打洞。注意很多人在内网测试时觉得不需要STUN但一旦浏览器和SIP服务器不在一台机器或跨网段候选收集不全就会导致单向或双不通。5.3 DTMF按键没反应现象通话建立后在页面上按键对方听不到按键音IVR流程无法触发。原因DTMF在WebRTC里有两条路一是通过RTP的RFC2833带内传输二是通过SIP协议发送INFO消息。SIP.js默认的sendDTMF走的是Session的DTMF方法它依赖对方和服务器支持RFC2833而很多老PBX只认SIP INFO。解决确认目标平台的DTMF偏好如果是老网关建议用SIP INFO方式。SIP.js层面可以在创建会话时手动指定DTMF模式或者在收到对方要求时走sip INFO的发送逻辑我用过的版本里直接改SIP消息头比较稳但也需要关注对端网关的配置策略这一步不是纯前端能完全兜住的。5.4 回铃音和彩铃不出现现象拨号后被叫方振铃但主叫方什么都听不到一直到对方接听才有声音。原因很多SIP服务器支持早期媒体Early Media也就是在被叫应答前就向主叫发送媒体流。SIP.js默认处理的是常规应答流程收到183或180后如果没开启自动应答早期媒体就不会把远端媒体送到audio元素。解决在UA构造参数里开启早期媒体支持并把sessionDescriptionHandlerOptions里的answerOn183设为true。这样收到183时就会提前建立媒体通道回铃音和运营商彩铃就能正常播放。注意只有对端网关支持183的前提下这个参数才有效老旧的SIP服务器直接发180的还是听不到。5.5 WebSocket连不上ws与wss混用的坑现象页面部署在HTTPS下但代码里写ws://控制台报Mixed Content或被浏览器直接阻止。原因浏览器安全策略要求HTTPS页面不能发起不安全的WebSocket连接。解决把transportOptions.server改成wss://并确保证书是浏览器可信任的。如果是开发环境可以在服务器或本机临时信任自签证书但生产环境必须用合法证书。还有变种情况SIP服务器走Nginx代理外部用的是wss://域名Nginx里没配/ws路径转发导致握手404。此时排查顺序是先直接访问wss://IP:端口测试再用域名访问两段分开排查能快速定位是Nginx还是证书还是服务器本身的问题。6. 更进一步把Demo演进成可交付的Web电话6.1 从Demo到完整电话模块要补的工程点Demo跑通只是第一步真实对话系统要考虑的问题远多于信令本身。我一般会按这个顺序去补第一是登录态管理SIP账号不能硬编码在前端要由后端签发临时密码或动态生成短时SIP凭据第二是重连与心跳WebSocket断开后要自动重连注册过期要自动刷新否则用户手机锁屏一会儿回来后电话就是“假在线”第三是通话排队同时只能有一个通话但来电可能在通话中到来这个时候要做“忙线拒接”或“呼叫保持”第四是日志上报前端收集SIP trace和媒体Stats统一发到日志中心否则线上问题你根本无法定位。6.2 构建时的注意点与浏览器兼容SIP.js虽然是纯JS库但构建时还是有几个容易踩的地方。一个是打包体积SIP.js未压缩的包体和它依赖的wrtc适配逻辑都不小建议用Tree Shaking和按需引入前后端打包分层。另一个是浏览器适配SIP.js依赖WebRTC的getUserMedia和RTCPeerConnection如果你的产品还要兼容旧版移动端WebView就需要引入webrtc-adapter做垫片不然会出现“安卓上能用iOS上注册都注册不了”的尴尬。第三个是构建环境里的一些Node原生模块比如crypto在浏览器构建时要用crypto-browserify这类polyfill垫住新版本改进了这点但旧项目升级时容易爆出这类错误。6.3 验证习惯在控制台里确认信令与媒体状态我自己的习惯是每次改动后先做三步验证第一打开控制台看trace事件里的SIP消息确认注册、INVITE、200 OK、ACK的时序是否正常第二在通话中调用getStats()确认音视频轨道都在传输丢包率在阈值内第三手动挂断和异常退出两种路径都要测确认bye、terminate、disconnected事件都能正确清理界面和媒体流。这三步走完基本可以把“信令通、媒体通、状态清”这三个层面都覆盖到。6.4 一个值得坚持的好习惯最后说一个我个人的习惯SIP.js的Demo调试过程中尽量保持“一次只改一个变量”。注册失败就只查WebSocket和鉴权不要顺手改编解码或界面无声就只查getUserMedia和设备权限不要同时换Server和改UA参数。因为WebRTC链路长信令、网络、媒体、设备任何一环出问题都会表现为“电话坏了”而变量一多你就分不清是哪一环在拖后腿。这条链路我已经走了很久翻过不少车最大的感受是不要对着黑匣子猜把信令log和Stats打开问题一定会自己浮出来。希望这个Demo和这套排查习惯能帮到你少走几段弯路。本文还有配套的精品资源点击获取