Vue3中基于JSSIP的SIP软电话实战：从注册到通话、调试与踩坑

做前端音视频和通信集成的朋友，对JSSIP应该不陌生。它是一个纯JavaScript实现的SIP客户端，跑在浏览器里就能注册分机、拨打外线、接听来电，底层信令传输走WebSocket，媒体通道走WebRTC。这套组合现在大量用在客服软电话、在线问诊、远程面签、虚拟号中介这类项目里，也是我在最近几个项目里绕不开的核心模块。这篇文章不打算复述官方文档，而是把我在Vue3项目中从注册到通话、从调试到压测的真实过程和踩过的坑整理出来，按“链路拆解—代码落地—问题排查—工具方法”的顺序讲，适合正在做WebRTC软电话、WebSocket长连接集成的前端开发者，也适合想了解SIP over WebSocket这套体系的服务端同学参考。

1. 项目整体思路：JSSIP、WebRTC、WebSocket三者怎么配合

1.1 一次通话链路里三个组件各管哪一段

很多人第一次接触JSSIP会有点晕，因为文档里一会儿讲WebSocket，一会儿讲WebRTC，一会儿又是SIP消息。实际在一条通话链路上，三者的分工非常清晰：WebSocket是信令的搬运工，JSSIP是信令的翻译官和状态机，WebRTC是媒体通道本身。

拿打电话来类比：你拿起电话拨号，运营商的交换机先帮你建立连接，这对应SIP信令；接通之后你们俩直接说话，这对应媒体流。浏览器里没有原生的SIP能力，所以JSSIP负责生成、解析、维护SIP消息，包括REGISTER注册、INVITE呼叫、BYE挂断、REFER转接等动作。这些SIP消息不直接走UDP 5060，而是封装成文本帧通过WebSocket发送给SIP服务器，服务器一般是FreeSWITCH、Kamailio或Asterisk。等INVITE协商完成，SDP里已经写好了编解码、DTLS指纹、ICE候选，浏览器之间或浏览器与媒体服务器之间就开始走RTP流，由WebRTC的RTCPeerConnection接管音频。

理解了这个分层，后面所有问题都能找到归属：注册不上是WebSocket和认证的问题，接通没声音是WebRTC媒体协商和NAT穿透的问题，通话中途断线是信令保活和心跳的问题。排查时先定位属于哪一层，效率会高很多。

1.2 为什么信令必须走WebSocket而不是UDP直连

传统SIP话机走UDP 5060或TCP 5060，浏览器做不到这一点，因为浏览器的网络能力被严格限制，没有裸socket可用，能用的双向长连接只有WebSocket。RFC 7118定义了SIP over WebSocket的封装方式，把SIP消息当作WebSocket的文本帧传输。这是JSSIP这类库能存在的协议基础。

实际项目中走WebSocket还有一个额外好处：WSS默认走443端口，和HTTPS同端口，几乎不会被企业防火墙拦。传统SIP话机经常因为办公室网络限制无法注册，但浏览器软电话很少遇到这种问题。对运维来说也很省心，只需要放行443，不需要给每台坐席电脑开UDP端口。

有一点需要注意：有些SIP代理服务器或SBC要求WebSocket握手时带上Sec-WebSocket-Protocol: sip这个子协议头，否则直接拒绝连接。JsSIP的WebSocketInterface底层WebSocket支持自定义header，如果遇到连接握手失败，优先检查这一步。Chrome版本升级后出现的“WebSocket连不上”问题，很多都和子协议、TLS证书校验变严有关，而不是代码本身出了问题。

1.3 JSSIP和原生WebRTC该怎么选

如果只是两个浏览器之间视频聊天，用原生RTCPeerConnection就够了，不需要引入SIP体系。但一旦涉及分机、外线、PSTN、坐席排队、通话录音这些业务电话能力，就必须有SIP信令，JSSIP几乎是浏览器端唯一成熟的选择。

我也见过团队想用原生WebRTC自己撸一套呼叫控制，最后都后悔了。不是WebRTC不行，而是SIP状态机太琐碎：注册刷新、鉴权摘要、事务重传、REFER的Replaces头、SDP的re-INVITE等，自己维护很容易漏。JSSIP把这些都封装好了，底层用的仍然是浏览器的RTCPeerConnection，但它负责创建会话、处理信令、触发音频元素，开发者的注意力可以放在业务上。

选型对比下来，我的建议是：纯网页视频通话用原生WebRTC；坐席软电话、呼叫中心、带分机体系的系统用JSSIP。如果项目里还要接后端业务，比如SpringBoot+Vue3集成WebSocket推送坐席状态，JSSIP和后端业务流程是解耦的，你只需要把通话事件同步给业务后端即可，架构非常清晰。

2. JSSIP核心接入：从注册到通话的完整实现

2.1 项目环境准备与UA单例初始化

先跑通一个最小可用的JSSIP实例。我用的是Vue3+Vite项目，安装依赖就一条命令：

npm install jssip

然后初始化UA。UA（User Agent）是JSSIP的核心对象，一个浏览器页面只需要一个UA实例，所以建议封装成单例服务，不要在组件里反复创建。下面这段是生产环境里可以用的初始化方式：

import JsSIP from 'jssip'; const socket = new JsSIP.WebSocketInterface('wss://sbc.example.com:7443'); const ua = new JsSIP.UA({ sockets: [socket], uri: 'sip:1001@example.com', password: 'your_password', displayName: '张三', registerExpires: 120, connectionTimeout: 10, sessionTimersExpires: 120, // 有需要时加上这个，部分SBC要求SIP子协议 // extraHeaders: { 'Sec-WebSocket-Protocol': 'sip' } });

几个容易踩坑的点：uri和sockets里的域名，生产环境建议保持一致。有的SBC会校验From头域和WebSocket连接来源是否匹配，不一致会直接403。registerExpires不要设太短，否则每次过期重注册会非常频繁，网络一抖动就疯狂刷REGISTER；也不要设太长，分机状态更新不及时。我习惯设120到300秒之间，服务器侧允许的范围内能小则小。

初始化和注册的动作是ua.start()，调用后JSSIP会先建立WebSocket连接，然后自动发REGISTER。UA的所有状态变化都通过事件对外通知，不要用定时器去轮询状态。

2.2 登录认证、注册保活和状态监控

注册流程的完整时序是：WebSocket握手成功后，客户端发REGISTER；服务器回401，带上随机nonce；客户端用密码和nonce算摘要，再次发REGISTER；服务器校验通过后回200 OK，带Expires字段。之后JSSIP内部会根据Expires自动在到期前重新REGISTER，这段逻辑你不用自己写，但要理解它是注册保活的根基。

前端要重点监听下面这几个事件：

ua.on('registered', () => { /* 注册成功，更新UI状态 */ }); ua.on('unregistered', () => { /* 注销或被服务器踢下线 */ }); ua.on('registrationFailed', (data) => { /* 401/403等，把data.cause展示给用户 */ }); ua.on('disconnected', () => { /* WebSocket断开，触发重连逻辑 */ });

认证这块要特别提醒：不要把SIP密码明文存在localStorage里，XSS一打就全没了。更稳妥的方案是后端提供临时凭证接口，每次登录时动态生成一个短期有效的SIP账号或密码，用完即换。如果项目暂时做不到，至少把密码放在环境变量里，构建时注入。

2.3 外呼、来电接听与事件清理

外呼的核心方法是ua.call()，来电的核心事件是newRTCSession。两者最终都落到一个RTCSession实例上，所有通话控制都是操作这个session。

// 外呼 const session = ua.call('sip:2002@example.com', { mediaConstraints: { audio: true, video: false } }); bindSessionEvents(session); // 来电 ua.on('newRTCSession', (data) => { const session = data.session; if (session.direction === 'incoming') { bindSessionEvents(session); // 业务上可以自动接听，也可以提醒用户接听 // session.answer({ mediaConstraints: { audio: true, video: false } }); } }); function bindSessionEvents(session) { session.on('accepted', () => { /* 通话已接通 */ }); session.on('confirmed', () => { /* 媒体通道建立完成 */ }); session.on('ended', () => { /* 通话结束，清理资源 */ }); session.on('failed', (data) => { /* 呼叫失败，data.cause有原因 */ }); }

来电接听有个很重要的细节：session.answer()调用的时机，最好绑定在用户点击接听按钮之后，这不仅是产品交互问题，还关系到后面要说的浏览器自动播放策略。挂断用session.terminate()，客户端会先发BYE，服务器回200后整个会话结束。

组件卸载或路由离开时，必须移除UA上的newRTCSession等全局监听器，否则组件销毁了监听还在，会引发重复振铃和内存泄漏。我在项目里专门封装了一个dispose()方法，统一移除所有UA和session监听器。

2.4 DTMF、保持、转接和设备切换的落地写法

通话中的操作，JSSIP给的API都比较直接：session.sendDTMF('1')发按键，session.hold()保持，session.unhold()恢复，session.mute({ audio: true })静音，session.refer('sip:2003@example.com')转接。

DTMF这里有个兼容性坑。JSSIP的sendDTMF默认走RFC 4733带内DTMF，也就是按键音跟着RTP媒体流一起发送，现代话机都支持。但一些老网关或第三方线路识别不了，这时要退化成SIP INFO方式，显式传方法参数：

session.sendDTMF('1', { method: 'info' });

转接是三个操作里最复杂的。session.refer()做的是盲转，直接把通话转移给对方，中间不需要咨询。如果要做带咨询的转接，流程是先用session.hold()保持当前通话，再ua.call()打给第三方，接通后再refer并带上Replaces头，把两路通话合并。这个流程在不同SBC上兼容性差异很大，我建议把转接相关的SIP头字段处理交给服务端B2BUA，前端只触发业务动作，不在浏览器里硬调。

设备切换用的是浏览器媒体能力，和JSSIP本身关系不大。通过navigator.mediaDevices.enumerateDevices()拿到麦克风和扬声器列表，切换扬声器时对JSSIP创建的audio元素调用audio.setSinkId(deviceId)。JSSIP的本地音频和远端音频是两个独立的audio元素，改输出设备时别漏了。

3. 踩坑实录：我在Vue项目中碰到的问题与修复

3.1 WebSocket断线重连与心跳保活的正确姿势

家用路由器NAT超时、公司Wi-Fi切换、笔记本休眠唤醒，都会导致浏览器和SBC之间的WebSocket连接被中间设备悄然掐断，但浏览器自己不知道，直到下一次信令发送失败才报错。最典型的场景是：坐席早上打开软电话页面，中午去吃饭电脑休眠，回来发现点“接听”没反应，刷新页面才好。

我的处理方案是双保险。第一层是监听ua.on('disconnected')事件，触发后手动调用ua.start()重新建立连接并注册。重连不能无脑高频重试，我用指数退避，按2秒、5秒、10秒、30秒的间隔递增，连续失败几次后停下来，等待用户手动点击“重新连接”。第二层是应用层心跳，注册成功后每30秒发一次WebSocket的Ping/Pong帧，这个比SIP OPTIONS更轻量，中间设备只要一段时间没看到活动包就会回收连接，心跳能有效防止NAT超时。

有一点必须说明：WebSocket断开不代表正在进行的通话会立刻中断，媒体流是独立的，但信令断了之后你无法挂断、无法保持、无法转接。所以页面里要监听disconnected事件，一旦触发就弹提示“网络连接中断，通话中的操作可能失败”，恢复后自动重连补REGISTER。

3.2 来电铃声不响：自动播放策略的绕过思路

这个坑几乎每个做JSSIP的人都会遇到。Chrome、Safari默认不允许网页自动播放有声音的媒体，用户没跟页面发生过任何交互之前，audio.play()会被拒绝。JSSIP收到来电INVITE后内部创建audio元素播放振铃音，结果就是来电显示在界面上，但一点声音没有。手机端更严格，锁屏或切后台后，WebSocket和媒体都可能被系统挂起。

解决思路分几层。最基础的是：登录页的“登录”按钮就是一次用户手势，点击后创建一个共享的AudioContext并立即resume()，把音频通道解锁。如果来电时AudioContext.state是suspended，说明用户还没有和页面交互过，这时候只能引导用户点击页面任意位置解锁。我做过一个兜底方案：来电时检测到音频无法播放，就弹一个高亮的系统通知，同时页面内闪烁振铃动画，至少不能让坐席漏接电话。

桌面端还有一个技巧：在用户首次点击按钮时播放一段极短的静音音频或调用audio元素的play()再立刻暂停，手动触发一次音频播放权限。但移动端Chrome对这种“假播放”识别得很严格，还是建议用AudioContext.resume()判断状态，状态不对就引导用户主动操作。

3.3 回声、啸叫与音量补偿的处理

软电话最难受的问题就是回声。坐席用笔记本自带的麦克风和扬声器接电话，对方能听到自己的声音回来，严重的时候形成刺耳啸叫。WebRTC内部自带AEC回声消除、NS降噪、AGC自动增益，默认开启，但实际效果取决于设备驱动和声学环境。

在ua.call()和answer()的mediaConstraints里，音频不要只写{ audio: true }，尽量把处理开关显式打开：

const session = ua.call('sip:2002@example.com', { mediaConstraints: { audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true }, video: false } });

即便如此，物理声学回声没法靠算法根治。免提外放的场景下，麦克风会采集到扬声器出来的声音，AEC只能抑制一部分。我的经验是坐席工位强制使用耳麦，或使用带硬回声消除的USB话机，软电话侧再配合AEC，才能达到能长时间通话的音质。

音量方面也有一个调优点：部分坐席反馈远端声音太小，JSSIP创建的session.remoteAudio音量可以适度放大。

const audio = document.getElementById('remoteAudio'); audio.volume = 1.2; // 超过1.5容易爆音，1.2-1.5是一个比较稳的范围

同时用navigator.mediaDevices.addEventListener('devicechange', ...)监听设备插拔，用户插拔耳机后自动切换默认输出设备，避免声音莫名消失。

3.4 通话计时漂移：用getStats拿真实统计

页面上的“通话时长”看起来是最简单的功能，一个setInterval累加就行，但真实环境下一测就露馅：笔记本盒盖休眠再打开，定时器被浏览器节流甚至暂停，通话时长比实际少了十几秒；手机浏览器切后台回来，定时器可能一次性补跳，显示的秒数直接乱掉。

原因是浏览器对后台标签页的定时器做了节流，移动端尤其激进。解决方案是不要用前端定时器作为计费依据，展示可以本地驱动，但精准数据要从WebRTC的统计接口拿，或者直接以服务器话单为准。

JSSIP的session底层就是RTCPeerConnection，可以通过它拿统计：

async function getCallStats(session) { const stats = await session.connection.getStats(); stats.forEach(report => { if (report.type === 'remote-inbound-rtp' || report.type === 'inbound-rtp') { console.log('RTT:', report.roundTripTime); console.log('丢包:', report.packetsLost); console.log('抖动:', report.jitter); } }); }

线上项目我建议这样组合：前端计时只是展示，通话开始时间以session.startTime为准，结束后向后端拉取话单，用服务器的start/end时间覆盖本地展示。这能避免因为前端计时不准引发的客诉，尤其是按分钟计费的业务。

3.5 弱网下的链路容量估计与码率自适应

网络差的时候，为什么不直接断音而是“卡一卡又恢复”？这是WebRTC的链路容量估计在起作用。WebRTC的传输层不是定码率硬传，而是通过网络反馈动态调整码率：延迟增大、丢包变多时，发送端自动调低音频或视频码率；网络恢复后再往上探。Google的GCC拥塞控制算法就是干这个的，它结合发送端的丢包反馈和接收端的延迟反馈，估算当前链路能承载的容量，再映射到编解码器码率。

在实际项目中，这块不需要你写算法，但需要理解现象：如果用户网络差，Opus编码会逐步降码率，视频会掉分辨率，这是正常的自适应过程，不是故障。真正需要排查的是明明网络不差但通话质量极差，这时候用getStats看roundTripTime和packetsLost，丢包率持续高于5%基本可以判断是网络链路问题或UDP被限速。

我有一个实战经验：用Chrome DevTools的Network条件里模拟弱网（比如下行1Mbps、上行512kbps），再发起通话，观察audioLevel和编解码状态，就能验证客户端在网络劣化时是否还能保持基本可用。如果模拟弱网直接断音，优先检查TURN中继是否配置正确，很多情况是UDP被防火墙阻断后媒体连不上，而不是业务代码的问题。

4. 调试与压测：从信令到媒体的排查链路

4.1 用DevTools、Postman和Wireshark排查信令

JSSIP项目调试的最大优势是：信令报文就在浏览器的DevTools里。打开Network面板，找到WebSocket类型的请求，点击进入Messages标签，能看到逐条收发的SIP文本消息。REGISTER、INVITE、100 Trying、180 Ringing、200 OK都有时间戳，排查注册失败、呼叫失败非常直观。

如果DevTools的WS面板不够用，比如要看WSS加密后的原始包，要么在浏览器启动时配置TLS密钥导出，要么直接在SIP服务器上抓包。服务器上一条命令就够了：

tcpdump -i any -s 0 port 7443 -w sip.pcap

把pcap文件拉到本地用Wireshark打开，通过Follow Stream看完整信令流。FreeSWITCH也可以直接开SIP trace，sofia global siptrace on会把所有信令打到日志里，前后端各留一份，两边对着排查效率最高。

Postman的WebSocket请求工具也可以用来验证SBC行为。手动连上wss://sbc.example.com:7443，往里面塞一条REGISTER消息，观察服务器的响应。适合快速确认SBC对子协议、鉴权头、过期时间的要求，但没法模拟完整的多轮交互，只能做辅助验证。

4.2 用JMeter WebSocket Sampler做注册压测

上线前要评估SBC能扛多少并发注册，这时候JMeter的WebSocket Sampler插件就派上用场了。插件通过Plugins Manager安装，搜“websocket”，对应的是WebSocket Samplers by Peter Doornbosch。JMeter里配置好wss地址，填入SIP REGISTER消息，用CSV变量控制分机号，就能模拟几百上千个分机同时注册。

有两个坑必须先解决。第一，REGISTER报文的Authorization摘要认证是一次性的，包含服务器下发的nonce，压测脚本里要处理401重传的流程，或者干脆在测试环境关闭SBC的鉴权。第二，不要用浏览器本身去压测，浏览器对同一域名的并发连接数有限制，JMeter走的是Java WebSocket客户端，不受这些限制，能直接压出服务器上限。

注册压测产出的结论很有价值。很多SBC是按注册分机数和并发通话数授权计费的，压测能帮你估算采购规格，避免钱花在永远用不到的高并发上。另外也要测长时间稳定连接场景，模拟坐席挂机后WebSocket常驻，连接数缓慢增长后会不会被服务器回收。

4.3 WebRTC本地地址泄露与隐私加固

WebRTC有一个很出名的隐私问题：浏览器原生WebRTC在ICE协商阶段会收集本机所有IP地址，包括内网LAN地址和通过STUN拿到的公网反射地址，并将这些作为candidate放进SDP发给对端。如果在公网P2P直连场景里禁用TURN，对端完全可以从SDP里读出你的内网IP。这个问题在很多合规审查里会被问到。

JSSIP项目同样绕不开：浏览器之间或浏览器与媒体服务器之间的SDP协商就是WebRTC的candidate交换。我的加固方案是强制媒体流走TURN中继，不启用host和srflx候选。这样对端只能看到relay地址，源IP被TURN服务器隐藏。虽然会增加一部分带宽成本，但换来了地址不可见和更稳定的穿透成功率，对软电话场景来说很划算。

有人会想从前端改SDP把host候选删掉，我不建议这么做。WebRTC规范没有提供官方的候选过滤API，手动munging SDP很容易破坏ICE校验和DTLS指纹，导致连接失败。更稳妥的是在服务器侧配置TURN并设置合适的候选策略，同时把STUN服务器限到受信任的设备上。

5. 常见问题排查速查表

5.1 高频问题排查速查表

这里把项目上线以来遇到的高频问题整理成了一张速查表，每一条都是真实出现过的，可以直接对着排查。

5.2 推荐的信令排查顺序

问题一多就容易乱抓，我总结了一套固定的排查链路，按这个顺序走，大部分问题能十分钟定位：

第一步看WebSocket连接状态。Network面板里WS连接必须是Established，握手失败先查证书、地址、子协议。第二步看REGISTER流程。DevTools WS消息里能看到406、401、200 OK，没到200之前都不算注册成功。第三步看呼叫信令。外呼以后INVITE要经过100 Trying、180 Ringing，最终到达200 OK，卡在哪一步，问题就在哪一段。第四步看媒体流。信令通了但没声音，用getStats看RTP包是否双向发送，哪边没包哪边有问题。第五步看设备和浏览器。确认麦克风权限、默认扬声器、页面是否处于前台。

这套顺序本质是“信令先行、媒体后置、设备兜底”，因为大多数问题其实都出在前三层，设备和浏览器反而是最后才需要怀疑的。养成按链路排查的习惯，能省掉非常多无效沟通。

这些流程和方法全部跑通之后，JSSIP在项目里就是一块非常稳定的拼图。我个人最后的体会是：JSSIP的能力边界非常清晰，它负责信令和会话控制，媒体质量靠WebRTC自身机制，业务状态靠后端系统协同，不要把一切问题都丢给前端库。前期花一点时间把信令时序、心跳保活、事件清理和getStats统计搞明白，后面上线维护的成本会低很多。如果后续还要扩展语音通知、IVR按键导航、坐席状态中心，基于这套信令体系做下去也顺理成章。希望这篇整理能帮大家少踩几个我已经踩过的坑。