RTCPeerConnection

Baseline 广泛可用 *

此功能已成熟，可跨多种设备和浏览器版本使用。自 2017 年 9 月以来，它已在浏览器中提供。

* 此特性的某些部分可能存在不同级别的支持。

RTCPeerConnection 接口表示本地计算机与远程对等端之间的 WebRTC 连接。它提供了连接到远程对等端、维护和监控连接以及在不再需要时关闭连接的方法。

构造函数

RTCPeerConnection(): 返回一个新的 RTCPeerConnection 对象，表示本地设备与远程对等端之间的连接。

实例属性

还继承了 EventTarget 的属性。

canTrickleIceCandidates 只读: 返回一个布尔值，指示远程对等端是否可以接受 trickled ICE 候选。
connectionState 只读: 通过返回以下字符串之一来指示对等连接的当前状态：new、connecting、connected、disconnected、failed 或 closed。
currentLocalDescription 只读: 返回一个 RTCSessionDescription 对象，描述此 RTCPeerConnection 自上次与远程对等端完成协商和连接以来，本地连接端最近一次成功协商的状态。其中还包括自描述所代表的要约或应答首次实例化以来，ICE 代理可能已经生成的任何 ICE 候选列表。
currentRemoteDescription 只读: 返回一个 RTCSessionDescription 对象，描述此 RTCPeerConnection 自上次与远程对等端完成协商和连接以来，远程连接端最近一次成功协商的状态。其中还包括自描述所代表的要约或应答首次实例化以来，ICE 代理可能已经生成的任何 ICE 候选列表。
iceConnectionState 只读: 返回一个字符串，表示与此 RTCPeerConnection 关联的 ICE 代理的状态。它可以是以下值之一：new、checking、connected、completed、failed、disconnected 或 closed。
iceGatheringState 只读: 返回一个字符串，描述连接的 ICE 收集状态。这让你可以检测到，例如，ICE 候选收集何时完成。可能的值为：new、gathering 或 complete。
localDescription 只读: 返回一个 RTCSessionDescription，描述连接本地端的会话。如果尚未设置，则返回 null。
peerIdentity 只读: 返回一个 Promise，该 Promise 解析为一个 RTCIdentityAssertion，其中包含一个标识远程对等端的字符串。一旦此 Promise 成功解析，则生成的身份为目标对等端身份，并且在连接期间不会更改。
pendingLocalDescription 只读: 返回一个 RTCSessionDescription 对象，描述连接本地端的待定配置更改。这不描述连接的当前状态，而是描述连接在不久的将来可能存在的方式。
pendingRemoteDescription 只读: 返回一个 RTCSessionDescription 对象，描述连接远程端的待定配置更改。这不描述连接的当前状态，而是描述连接在不久的将来可能存在的方式。
remoteDescription 只读: 返回一个 RTCSessionDescription 对象，描述连接远程端的会话，包括配置和媒体信息。如果尚未设置，则返回 null。
sctp 只读: 返回一个 RTCSctpTransport 对象，描述正在通过其发送和接收 SCTP 数据的 SCTP 传输层。如果尚未协商 SCTP，则此值为 null。
signalingState 只读: 返回一个字符串，描述连接到另一个对等端时，连接本地端信令过程的状态。它是以下值之一：stable、have-local-offer、have-remote-offer、have-local-pranswer、have-remote-pranswer 或 closed。

静态方法

RTCPeerConnection.generateCertificate(): 创建 X.509 证书及其相应的私钥，并返回一个 Promise，该 Promise 在生成新 RTCCertificate 后解析为它。

实例方法

还继承了 EventTarget 的方法。

addIceCandidate(): 向 RTCPeerConnection 的远程描述添加新的远程候选，该描述描述了连接远程端的状态。
addTrack(): 向将传输到另一个对等端的轨道集添加新的 MediaStreamTrack。
addTransceiver(): 创建新的 RTCRtpTransceiver 并将其添加到与连接关联的收发器集。每个收发器都表示一个双向流，并与其关联一个 RTCRtpSender 和一个 RTCRtpReceiver。
close(): 关闭当前对等连接。
createAnswer(): 在 WebRTC 连接的要约/应答协商期间，启动创建对从远程对等端收到的要约的 SDP 应答。应答包含有关已附加到会话的任何媒体、浏览器支持的编解码器和选项以及已收集的任何 ICE 候选的信息。
createDataChannel(): 启动创建与远程对等端链接的新通道，通过该通道可以传输任何类型的数据。这对于后台内容（例如图像、文件传输、文本聊天、游戏更新包等）非常有用。
createOffer(): 启动创建 SDP 要约，以启动到远程对等端的新 WebRTC 连接。SDP 要约包括有关已附加到 WebRTC 会话的任何 MediaStreamTrack 对象、编解码器和浏览器支持的选项的信息，以及 ICE 代理已收集的任何候选，目的是通过信令通道发送给潜在的对等端，以请求连接或更新现有连接的配置。
getConfiguration(): 返回一个对象，指示连接的当前配置。
getIdentityAssertion(): 启动身份断言的收集并返回一个 Promise，该 Promise 解析为编码为字符串的身份断言。这仅在 signalingState 不是 closed 时才有效。
getReceivers(): 返回一个 RTCRtpReceiver 对象数组，每个对象表示一个 RTP 接收器。
getSenders(): 返回一个 RTCRtpSender 对象数组，每个对象表示负责传输一个轨道数据的 RTP 发送器。
getStats(): 返回一个 Promise，该 Promise 解析为提供有关整个连接或指定 MediaStreamTrack 的统计数据。
getTransceivers(): 返回一个列表，其中包含用于在连接上发送和接收数据的所有 RTCRtpTransceiver 对象。
removeTrack(): 通知连接的本地端停止发送指定轨道的媒体，而无需实际从 getSenders() 报告的发送器列表中删除相应的 RTCRtpSender。如果轨道已经停止或不在连接的发送器列表中，则此方法无效。
restartIce(): 允许轻松请求在连接的两端重新执行 ICE 候选收集。这通过允许调用方或接收方使用相同的方法触发 ICE 重启来简化该过程。
setConfiguration(): 根据指定对象中包含的值设置连接的当前配置。这允许您更改连接使用的 ICE 服务器和要使用的传输策略。
setIdentityProvider(): 将身份提供商 (IdP) 设置为参数中给出的三元组：其名称、用于与其通信的协议和用户名。协议和用户名是可选的。
setLocalDescription(): 更改与连接关联的本地描述。此描述指定连接本地端的属性，包括媒体格式。它返回一个 Promise，该 Promise 在描述异步更改后实现。
setRemoteDescription(): 将指定的会话描述设置为远程对等端的当前要约或应答。该描述指定连接远程端的属性，包括媒体格式。它返回一个 Promise，该 Promise 在描述异步更改后实现。

已废弃的方法

addStream() 已弃用非标准: 将 MediaStream 添加为本地音频或视频源。与其使用此过时方法，不如为您希望发送到远程对等端的每个轨道使用 addTrack() 一次。
createDTMFSender() 已弃用非标准: 创建与特定 MediaStreamTrack 关联的新 RTCDTMFSender，该对象将能够通过连接发送 DTMF 电话信令。
removeStream() 已弃用非标准: 从本地音频或视频源中移除 MediaStream。由于此方法已过时，因此应改用 removeTrack()。

事件

使用 addEventListener() 监听这些事件，或通过将事件监听器分配给此接口的 oneventname 属性。

connectionstatechange: 当 RTCPeerConnection 的整体连接状态发生变化时发送。
datachannel: 当远程对等端向连接添加 RTCDataChannel 时发送。
icecandidate: 发送以请求将指定的候选传输到远程对等端。
icecandidateerror: 如果在 ICE 候选收集期间发生错误，则发送到连接。事件描述了该错误。
iceconnectionstatechange: 当 ICE 连接状态发生变化时发送，例如断开连接时。
icegatheringstatechange: 当 ICE 层的收集状态（由 iceGatheringState 反映）发生变化时发送。这表示 ICE 协商是否尚未开始 (new)、已开始收集候选 (gathering) 或已完成 (complete)。
negotiationneeded: 当需要执行 ICE 连接的协商或重新协商时发送；这既可能在首次建立连接时发生，也可能在需要适应不断变化的网络条件时发生。接收方应通过创建要约并将其发送给其他对等端来响应。
signalingstatechange: 当连接的 ICE 信令状态发生变化时发送。
track: 当新轨道已添加到构成连接的 RTCRtpReceiver 实例之一后发送。

过时事件

addstream 已弃用非标准: 当新 MediaStream 已添加到连接时发送。与其监听此过时事件，不如监听 track 事件；对于添加到连接的每个 MediaStreamTrack，都会发送一个事件。
removestream 已弃用非标准: 当 MediaStream 从连接中移除时发送。与其监听此过时事件，不如监听每个流上的 removetrack 事件。

规范

规范
WebRTC：浏览器中的实时通信 # 接口定义

浏览器兼容性

另见

https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
WebRTC 入门
TutorRoom：Node.js HTML 视频捕获、点对点视频和文件共享应用程序（GitHub 上的源代码）

帮助改进 MDN

了解如何贡献

本页面上次由 MDN 贡献者于 2025 年 9 月 25 日修改。

在 GitHub 上查看此页面 • 报告此内容问题