在线咨询
专属客服在线解答,提供专业解决方案
工单支持
专业技术支持团队,随时响应服务需求

werift 发布 v0.28.0,Node.js 开发 WebRTC 服务端需要注意什么?

2026 年 11 月 19 日,开源 WebRTC 项目 werift 发布 v0.28.0。新版本调整了浏览器标准兼容配置,新增 ICE Candidate 收集错误事件,并改进了 SDP 协商、DTLS 连接关闭及 RTP 媒体处理等功能。werift 是一个使用 TypeScript 编写的 WebRTC 协议栈,主要运行于 Node.js 环境。它是供开发者构建媒体服务器、音视频网关、录制服务和自定义实时通信应用的开源组件。

与浏览器原生 WebRTC 不同,Node.js 服务端需要自行管理媒体连接、协议协商及相关资源。即使浏览器已经支持 WebRTC,服务端仍可能遇到 ICE 连接失败、SDP 协商不兼容、视频轨道恢复异常等问题。

werift v0.28.0 的更新集中在这些工程细节上。其中,部分改动改变了默认连接行为,部分功能则提供了更明确的兼容选项和错误信息。对于已经使用 werift 构建实时通信服务的开发者,升级之前有必要了解这些变化。


一. werift 是什么?为什么 Node.js 需要 WebRTC 协议栈?

WebRTC(Web Real-Time Communication)是一套支持实时音视频和数据通信的技术体系。Chrome、Firefox、Safari 等现代浏览器已经提供了 WebRTC API,开发者可以通过 RTCPeerConnection 建立连接,使用 MediaStreamTrack 传输音视频,或者利用 RTCDataChannel 交换数据。

但浏览器支持 WebRTC,并不意味着 Node.js 服务端可以直接使用浏览器内置的媒体协议实现。

例如,一款远程摄像头应用需要将设备视频发送到服务器,服务器再将视频转发给其他终端。接收和处理媒体流的服务器必须具备与 WebRTC 客户端协商、建立安全连接和处理 RTP 数据的能力。

werift 提供了这一能力。它用 TypeScript 实现 WebRTC 协议栈,并提供与浏览器相似的 RTCPeerConnection API。

1. werift 包含哪些协议能力?

协议或模块 主要作用
SDP 交换音视频能力、媒体参数和连接信息
ICE 收集候选地址、进行连接检查、选择通信路径
STUN / TURN 获取网络地址信息,以及在必要时通过中继连接
DTLS 协商安全连接,并为媒体加密提供密钥材料
SRTP / SRTCP 保护音视频媒体及相关控制数据
RTP / RTCP 传输音视频数据及相关反馈信息
SCTP / DataChannel 在 WebRTC 连接中传输应用数据

这些协议在连接建立和数据传输过程中承担不同职责。

例如,ICE 首先尝试找到双方能够通信的网络路径。DTLS 负责安全握手,音视频数据则通过 SRTP 在选定的 ICE 路径上传输。DataChannel 使用 SCTP over DTLS 传递应用数据。

需要注意,音视频 RTP 数据并不是先封装进 DTLS 再传输。DTLS 主要承担安全握手和密钥协商,媒体数据使用 SRTP 保护后通过相应传输路径发送。

2. werift 适合开发哪些应用?

werift 的一个特点是开发者不仅可以使用 RTCPeerConnection,还可以访问部分较底层的 RTP、RTCP 和传输状态信息。

因此,它比较适合以下场景:

  • 媒体网关:在 WebRTC 与其他媒体系统之间接收、处理或转发数据。
  • 实时录制:接收客户端音视频,并交由录制或存储模块处理。
  • 自定义媒体服务器:开发媒体路由、测试 Peer 或特定业务的转发逻辑。
  • 机器人远程交互:接收机器人摄像头视频,交换设备状态和控制消息。
  • 实时 AI 应用:将客户端音频接入语音识别、模型处理或其他媒体流水线。

不过,werift 主要提供 WebRTC 协议实现,并不是一套开箱即用的生产级 SFU、视频会议平台或对话式 AI 服务。

如果需要多用户媒体路由、全球网络覆盖、音视频质量优化、监控和完整的业务管理能力,还需要开发者自行构建,或者选择相应的 RTC 服务。


二. werift v0.28.0 更新了什么?

从官方 Release Notes 看,本次版本更新涉及兼容配置、ICE、DTLS、SDP 和 RTP 等多个部分。

其中,比较值得开发者关注的变化包括:

  • 统一标准兼容配置的命名,并提供 compatibility 预设。
  • 调整 ICE Candidate 提名策略及连接状态处理。
  • 新增 icecandidateerror 事件,帮助定位 STUN/TURN 访问失败。
  • 新增 bundleCandidates 配置,减少特定 BUNDLE 会话中的重复候选信息。
  • 改进 DTLS Alert、连接关闭及错误状态处理。
  • 修复部分 SIP/WebRTC 网关 SDP 和 RTP 兼容问题。
  • 增加 RTP Timeline Rewriter,支持上游媒体源切换时维持下游 RTP 时间线。

1. compatibility:统一浏览器标准兼容配置

WebRTC 已有明确的标准,但不同实现可能保留各自的历史行为。

werift 过去使用 compatible、strict、peerConnection 等不同配置名称,分别表示浏览器兼容行为或项目自身的实现方式。

v0.28.0 将标准或浏览器兼容行为统一命名为 standard,并提供以下配置:

import { RTCPeerConnection } from "werift";

const pc = new RTCPeerConnection({
  compatibility: "standard"
});

该预设会将 certificateScope、mLineReuse、transceiverPairing 和 keyFrameRequestRouting 等兼容选项设置为 standard。

其中,certificateScope 涉及 DTLS 证书作用域;mLineReuse 影响 SDP 媒体部分的复用;transceiverPairing 决定远端媒体描述如何匹配本地收发器;keyFrameRequestRouting 则与关键帧请求的路由行为有关。

需要注意,v0.28.0 并没有直接将所有默认配置切换为浏览器标准模式。多数默认行为仍然兼顾旧版本使用方式。

因此,如果现有项目需要与浏览器的协商行为尽可能一致,可以评估 compatibility: “standard”。但启用之前仍应进行回归测试,不能认为加上这一配置就能消除全部 WebRTC 兼容问题。

2. bundleCandidates:减少 SDP 中重复的 ICE Candidate

当 WebRTC 连接同时包含音频、视频和 DataChannel 时,SDP 中可能出现多个 m-line。

m-line 用于描述一个媒体部分,例如音频轨道、视频轨道或应用数据通道。多个 m-line 可以通过 BUNDLE 共享底层传输。

在 werift 之前的默认行为中,同一 BUNDLE 组里的多个 m-line 可能重复包含相同的 ICE Candidate。

举个例子,如果一个连接有 7 个 m-line,底层收集到 12 个候选地址,按旧的重复写入方式,SDP 可能出现 84 行 a=candidate。

虽然这些候选地址对应的底层传输并没有增加,但 SDP 文本会随着媒体部分数量增长。

v0.28.0 新增 bundleCandidates 配置:

const pc = new RTCPeerConnection({
  bundleCandidates: "compatible"
});

在兼容模式下,同一 BUNDLE 传输的候选地址主要写入对应的 BUNDLE tag m-line,避免在其他共享传输的媒体部分中重复列出。

这有助于控制 SDP 大小,尤其适用于长时间运行、频繁新增媒体轨道或 DataChannel 的连接。

不过,该配置默认仍为 legacy。原因是部分已有应用或 SFU 可能依赖每个 m-line 都包含候选地址的旧格式。

因此,升级时可以先比较两种配置生成的 SDP,再测试浏览器、网关及现有媒体服务器的处理结果。

3. ICE 提名策略:连接建立行为更接近浏览器

ICE 不仅需要检查哪些候选地址可以连通,还需要确定最终使用哪一组候选地址进行通信。

这个选择过程称为 Candidate Pair Nomination,即候选地址对提名。

v0.28.0 将控制端的默认提名策略调整为更接近浏览器实现的半激进式提名,并改进了被控制端对后续提名结果的处理。

这项变化对 ICE 连接状态有实际影响。

例如,开发者之前可能在检测到可用 Candidate Pair 后,立即读取 getSelectedCandidatePair(),并假设它已经返回最终的通信路径。

新版本中,在 Candidate Pair 尚未正式被提名之前,该接口可能返回 null。

因此,应用不应仅凭已经发现可用候选地址,就认定 ICE 连接已经进入稳定的传输状态。

如果项目对 ICE 提名行为有特殊要求,werift 仍提供 iceNomination 配置,可根据需要选择符合 RFC 8445 的 regular nomination。

4. DTLS:连接失败与正常关闭的状态更加明确

实时通信服务端通常需要长期维护大量 PeerConnection。

如果连接关闭时没有正确释放 DTLS、SCTP 和 ICE 相关资源,或者错误状态没有及时传递到上层,可能造成连接状态异常和资源管理问题。

v0.28.0 改进了 DTLS Alert 的发送与接收,包括正常关闭通知 close_notify、致命错误处理以及证书验证失败时的反馈。

在新版本中,远端发送的正常关闭通知与致命 DTLS 错误会得到不同处理。对于证书指纹不匹配等情况,系统也能够提供更明确的错误状态。

此外,RTCPeerConnection.close() 会同步将连接状态设置为 closed,并进一步关闭对应传输资源。

对开发者而言,重要的是将正常关闭、网络中断和安全握手失败分开记录,不要把所有连接结束都统计成同一种异常。


三. Node.js 开发 WebRTC 服务端,最容易遇到哪些问题?

werift 提供了较完整的协议实现,但实际部署仍然需要处理网络环境、媒体协商及连接生命周期等问题。

1. ICE 连接失败,如何判断是不是 STUN/TURN 的问题?

WebRTC 连接建立通常需要收集本地候选地址,并根据网络环境尝试直接通信或使用 TURN 中继。

如果用户处于企业防火墙、运营商 NAT 或限制 UDP 的网络环境中,连接可能无法通过预期路径建立。

排查时至少需要确认:

  • STUN/TURN 地址、端口及协议配置是否正确。
  • TURN 用户名和密码是否有效。
  • 服务器防火墙是否允许相应协议和端口访问。
  • 连接双方是否完成 Candidate 交换。
  • ICE 状态是否进入 connected 或 completed。

v0.28.0 新增 icecandidateerror 事件,可以在候选地址收集过程中报告 STUN/TURN 访问失败。

例如:

pc.addEventListener("icecandidateerror", (event) => {
  console.error("ICE server error:", {
    url: event.url,
    code: event.errorCode,
    message: event.errorText
  });
});

如果 TURN 服务器返回认证错误,事件可能包含对应的 STUN 错误码;如果服务器无法访问,则可能产生 701 错误。

需要注意,出现 icecandidateerror 不一定代表整个 WebRTC 连接失败。因为某个 STUN/TURN 服务器访问异常时,其他候选路径仍可能成功建立连接。

因此,还应结合 ICE 状态、Candidate Pair 统计及实际数据传输情况分析。

2. SDP 协商成功,为什么仍然收不到视频?

SDP 协商完成,只能说明双方交换并接受了相关会话描述,不能保证后续 RTP 数据一定被正确接收和处理。

例如,某些 SIP/WebRTC 网关发送的 SDP 中没有提供 a=ssrc 属性。

如果服务端只能依赖 SDP 中预先声明的 SSRC 建立媒体路由,真正的 RTP 包到达时就可能找不到对应接收器。

werift v0.28.0 修复了这类情况:在满足条件时,可以根据收到的 RTP 包及 MID、Payload Type 等信息识别媒体来源,并学习此前未在 SDP 中声明的 SSRC。

这有利于与部分 SIP 网关、SBC 和媒体服务器互通。

但这种识别并非无限制接受未知媒体。对于无法明确归属的 RTP、未知 Payload Type 或其他不符合要求的数据,仍然会拒绝处理。

此外,新版本还修复了 a=rtcp 属性的解析问题。对于只包含端口号、没有显式地址的合法 a=rtcp 描述,服务端现在可以正确解析,而不是直接抛出异常。

如果出现 SDP 协商后没有画面的情况,建议按照以下顺序检查:

  • 音视频轨道是否正确建立,方向是否匹配。
  • SDP 中的 Codec、Payload Type、MID 和 SSRC 是否能够对应。
  • ICE、DTLS 和 SRTP 是否已经正常建立。
  • RTP 包是否实际进入服务端。
  • 接收器是否正确识别媒体来源。
  • 视频解码是否获得所需的关键帧。

3. 摄像头切换或重连后,为什么画面会异常?

一些实时视频应用需要在同一连接中切换摄像头,或者在上游设备掉线后重新建立媒体连接。

此时,上游 RTP 流的 SSRC、Sequence Number 和 Timestamp 可能发生变化。

如果直接把新源的 RTP 数据转发给原有下游连接,下游可能看到时间戳或序列号突然跳变,进而影响丢包判断、重排序和媒体恢复。

werift v0.28.0 新增 RtpTimelineRewriter,用于在切换上游媒体源时重写必要的 RTP 时间线信息,帮助下游维持连续的序列号与时间戳关系。

官方同时提供摄像头切换及重新创建上游连接的参考示例。

但要注意,RTP 时间线连续并不意味着切换后的画面一定立即可解码。如果视频新源尚未提供关键帧,客户端仍可能需要等待可解码帧。

因此,媒体切换时还需要结合 PLI、关键帧获取、Payload Type 和 SSRC 等信息共同处理。

4. 多连接服务端,怎样避免资源长期占用?

Node.js 应用可以同时创建多个 RTCPeerConnection,但每个连接都可能涉及 ICE、DTLS、SCTP、RTP 数据处理及相关定时器。

如果客户端断开后没有及时清理连接,长时间运行的服务可能出现内存占用增长、无效连接保留以及异常事件持续触发的问题。

因此,生产系统至少需要维护连接创建时间、最近活跃时间、ICE 状态、连接失败原因和关闭记录。

对于视频或音频服务,还应关注 RTP 收发速率、丢包、RTT、抖动和关键帧请求情况。

werift 提供 getStats() 及底层事件,可以用于建立基础监控。但实际监控平台、告警规则、容量规划和故障恢复仍需要应用自行实现。


四. 使用 werift 搭建一个最小 DataChannel 示例

对于首次接触 werift 的开发者,建议先验证 DataChannel,再扩展到音视频收发。

原因是 DataChannel 不需要额外处理摄像头、麦克风、编码格式或视频渲染。它能够帮助开发者先确认 SDP、ICE、DTLS 和 SCTP 链路是否正常。

下面的最小示例使用两个 Node.js 端的 RTCPeerConnection,在同一个进程中完成协商,并通过 DataChannel 互相发送消息。

这个示例主要用于验证 werift 的基本 API,并不等于已经搭建好一个可供公网浏览器访问的 WebRTC 服务端。

1. 安装 werift

建议使用 Node.js 22 或更新版本,创建项目并安装指定版本:

mkdir werift-demo
cd werift-demo

npm init -y
npm install werift@0.28.0

npm pkg set type=module

2. 创建 PeerConnection 和 DataChannel

新建 index.mjs,写入以下代码:

import { RTCPeerConnection } from "werift";

const offerer = new RTCPeerConnection();
const answerer = new RTCPeerConnection();

answerer.ondatachannel = ({ channel }) => {
  channel.onmessage = ({ data }) => {
    console.log("Server received:", data.toString());
    channel.send("Hello from answerer");
  };
};

const channel = offerer.createDataChannel("demo");

channel.onopen = () => {
  console.log("DataChannel connected");
  channel.send("Hello from offerer");
};

channel.onmessage = ({ data }) => {
  console.log("Offerer received:", data.toString());

  // 演示完成后主动释放资源
  offerer.close();
  answerer.close();
};

await offerer.setLocalDescription(
  await offerer.createOffer()
);

await answerer.setRemoteDescription(
  offerer.localDescription
);

await answerer.setLocalDescription(
  await answerer.createAnswer()
);

await offerer.setRemoteDescription(
  answerer.localDescription
);

运行:

node index.mjs

连接成功后,预期能够看到双方交换的消息。

在这个示例中,两个 PeerConnection 直接交换 SDP,不需要额外部署信令服务。

werift 的 setLocalDescription() 会在相应流程中等待候选地址收集,因此上述简化示例可以直接使用 localDescription 完成协商。

3. 如何扩展为真正的 Node.js WebRTC 服务端?

实际项目需要让浏览器和服务器之间交换 Offer、Answer 及必要的 ICE Candidate。

通常可以通过 HTTP 或 WebSocket 实现信令。

例如:

  1. 浏览器创建 RTCPeerConnection 和 DataChannel。
  2. 浏览器生成 Offer,通过 HTTPS 发送给 Node.js 服务端。
  3. 服务端使用 werift 创建 RTCPeerConnection,设置远端 Offer。
  4. 服务端生成 Answer,并将结果返回浏览器。
  5. 双方根据网络环境完成 ICE Candidate 交换和连接检查。
  6. DataChannel 建立后,浏览器与服务器直接通过 WebRTC 传输数据。

如果采用 Trickle ICE,还需要处理候选地址逐步交换与添加,以及候选收集完成状态。

公网部署时,信令服务还需要身份认证、连接鉴权、访问控制和必要的 HTTPS/WSS 安全配置。

如果下一步需要传输机器人视频,则应增加媒体轨道处理、RTP 收发以及视频编码兼容性测试。


五. werift、Pion、aiortc 和 RTC 服务应该怎么选?

开源 WebRTC 协议栈可以让开发者控制底层连接和媒体处理流程,但不同项目的技术栈和适用方向有所区别。

方案 技术栈 主要特点 适合场景
werift TypeScript / Node.js 协议栈可检查、可扩展,便于自定义媒体和连接逻辑 Node.js 媒体网关、协议开发、测试工具
Pion WebRTC Go 提供 Go 语言 WebRTC API 和协议能力 实时媒体服务、网关及自定义 WebRTC 应用
aiortc Python 易于与 Python 媒体和 AI 生态集成 计算机视觉、机器人、AI 原型和媒体处理

如果开发者主要目的是研究 WebRTC 协议,或需要定制 RTP 路由、媒体网关和连接行为,werift、Pion、aiortc 这类开源项目比较适合。

在声网,连接无限可能

想进一步了解「对话式 AI 与 实时互动」?欢迎注册,开启探索之旅。

本博客为技术交流与平台行业信息分享平台,内容仅供交流参考,文章内容不代表本公司立场和观点,亦不构成任何出版或销售行为。