Heygen流式Avatar WebRTC ICE连接持续处于Checking状态求助

一、先解决start_session接口400错误 #

400属于客户端请求参数错误，直接核对以下几点：

• 确认请求体里的session_id和创建会话返回的完全一致，client_sdp格式符合SDP标准（检查有没有语法错误，比如缺失字段、换行符异常）
• 验证请求头的Authorization token是否有效，有没有过期，或者账号是否开通了Heygen WebRTC相关权限
• 确保请求的content-type设为application/json，避免参数解析失败

二、处理STUN事务403禁止IP问题 #

STUN 403大概率是你的公网IP被Heygen的STUN服务器限制，或者网络环境存在拦截：

• 更换网络测试（比如切换手机热点、换其他运营商网络），排除IP被拉黑的可能
• 严格使用Heygen官方指定的STUN服务器，不要私自替换成第三方地址
• 检查本地防火墙、代理或者公司内网规则，有没有拦截STUN请求（比如端口限制）

三、排查on_ice_candidate事件未触发的情况 #

ICE候选不生成直接导致连接卡壳，从这几个方向排查：

• 核对RTCPeerConnection的配置，确保iceServers参数正确：

  const pc = new RTCPeerConnection({
    iceServers: [
      { urls: 'stun:stun.l.google.com:19302' }, // 或Heygen提供的官方STUN地址
      // 有TURN服务器的话也要配置正确
    ]
  });
  

• 确认onicecandidate事件绑定正确，注意大小写（不要写成onIceCandidate）：

  pc.onicecandidate = (event) => {
    if (event.candidate) {
      // 发送候选到Heygen服务器的逻辑
      console.log('ICE候选生成:', event.candidate);
    } else {
      console.log('ICE候选收集完成');
    }
  };
  

• 检查创建offer/answer后是否正确设置了本地描述——这是触发ICE收集的必要前提：

  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  // 之后把offer作为client_sdp传给start_session接口
  

• 打开浏览器的WebRTC调试工具（Chrome用chrome://webrtc-internals/），查看ICE收集是否启动，有没有隐藏的报错日志

四、额外排查点 #

• 检查Heygen返回的server_sdp是否有效，拿到后有没有正确设置远程描述：

  const serverSdp = // start_session接口返回的server_sdp
  await pc.setRemoteDescription(new RTCSessionDescription(serverSdp));
  

• 确认应用运行环境：非本地环境必须使用HTTPS（localhost除外），否则浏览器会限制WebRTC功能
• 联系Heygen技术支持，确认你的账号是否有WebRTC会话的配额限制，或者后台有没有相关报错日志

内容的提问来源于stack exchange，提问作者Eliott Eccidio