WebRTC中onIceCandidate不触发的根本原因，是未在createOffer()后立即且正确调用setLocalDescription()——该调用非可选步骤，而是激活ICE Agent的强制开关，漏掉则ICE收集永久卡死。
webrtc中`onicecandidate`不触发的根本原因，是未在`createoffer()`后**立即且正确调用`setlocaldescription()`**——该调用非可选步骤，而是激活ice agent的强制开关，漏掉则ice收集永久卡死。
在WebRTC点对点连接建立过程中，onIceCandidate事件沉默并非偶然故障，而是一个高度敏感的时序契约被破坏的明确信号。根据W3C WebRTC 1.0规范（§5.4 Set the session description），setLocalDescription()不仅是“保存SDP”，更是启动ICE Agent、触发候选者收集的唯一入口。一旦跳过或延迟该调用，RTCPeerConnection将永远停留在iceGatheringState = "new"或"gathering"状态，onIceCandidate自然永不触发——控制台甚至不会报错，仅表现为连接长期卡在iceConnectionState = "checking"后失败。
✅ 正确执行顺序（不可颠倒）
必须严格遵循以下原子化、异步安全流程：
// ✅ 正确：使用 async/await 或链式 Promise 确保时序
peerConnection.createOffer()
.then(offer -> {
Log.d(TAG, "Offer created: " + offer.description);
// ? 关键：立即 setLocalDescription 并 await 完成
return peerConnection.setLocalDescription(offer); // 返回 Promise！
})
.then(() -> {
// ✅ 此时 ICE 收集已启动，onIceCandidate 开始触发
Log.d(TAG, "Local description set — ICE gathering STARTED");
// ✅ 现在可安全监听候选者
peerConnection.registerObserver(new PeerConnection.Observer() {
@Override
public void onIceCandidate(IceCandidate candidate) {
if (candidate != null) {
// ? 必须逐条实时发送，不可缓存/合并
String candidateJson = new JSONObject()
.put("type", "candidate")
.put("candidate", candidate.sdp)
.put("sdpMid", candidate.sdpMid)
.put("sdpMLineIndex", candidate.sdpMLineIndex)
.toString();
websocket.send(candidateJson);
}
}
// ... 其他回调
});
})
.catch(e -> Log.e(TAG, "SDP setup failed", e));⚠️ 常见致命错误：
- ❌
pc.setLocalDescription(offer).then(...)中未return该 Promise → 后续.then()在setLocalDescription完成前就执行；- ❌ 在
createOffer().then()内直接调用setLocalDescription()但忽略其返回的Promise → 异步流断裂；- ❌ 使用
SimpleSdpObserver等无返回值回调 → 完全失去时序控制。
? 关于SDP与ICE候选者的混淆澄清
你观察到的SDP文本中包含a=candidate:行（如a=candidate:... typ host），这是内嵌候选（in-band candidates），仅在a=ice-options:trickle未启用时存在。而你的SDP中明确含有：
a=ice-options:trickle renomination
这表示双方协商采用Trickle ICE（渐进式候选交换）——即：
- ✅ SDP（offer/answer）只负责媒体能力协商，不含候选；
- ✅ 所有ICE候选必须通过独立信令消息（
{type: "candidate", ...}）逐条、实时发送； - ❌ 将SDP中的
a=candidate:行误当作有效候选提取并发送，会导致对方addIceCandidate()失败（格式不匹配）； - ❌ 拼接多个候选再发送，或添加防抖延迟，会使对方无法及时发起连通性检测，导致超时失败。
? 实操建议与检查清单
验证ICE收集是否真正启动：
监听onIceGatheringChange，确认状态从"new"→"gathering"→"complete"；若始终为"new"，必未调用setLocalDescription。-
检查STUN/TURN配置有效性：
当前代码使用了8个Google STUN服务器，但部分可能因网络策略失效。建议精简为1–2个高可用STUN（如stun:stun.l.google.com:19302），并务必添加TURN中继备用（尤其在企业NAT/防火墙环境下）：IceServer turnServer = PeerConnection.IceServer.builder("turn:your-turn-server.com:3478") .setUsername("user").setPassword("pass").createIceServer(); iceServers.add(turnServer); 升级SDK版本（安全刚需）：
你使用的org.webrtc:google-webrtc:1.0.32006发布于2022年，已知存在CVE-2023-24512等高危漏洞，且缺乏对AV1、E2EE等现代特性的支持。立即升级至最新稳定版（如1.1.0+），并同步更新WebRTCnative库。连接建立完成的标志：
当双方均收到对方全部ICE候选、且iceConnectionState变为"connected"或"completed"时，媒体流即开始传输。无需额外“发起呼叫”方法——WebRTC是事件驱动模型，状态变更即意味着就绪。
? 总结：WebRTC不是API调用，而是状态机协约
WebRTC的成功不取决于代码行数，而在于对signalingState、iceGatheringState、iceConnectionState三大状态机演进逻辑的精准把控。setLocalDescription()是ICE生命周期的“点火开关”，setRemoteDescription()是媒体轨道的“激活指令”，而每一条candidate消息都是建立连接的“时间敏感脉冲”。唯有恪守规范时序，方能穿越NAT迷雾，抵达实时通信的本质。
