使用Agora Web SDK构建视频聊天应用时WebSocket连接失败排查

问题描述 #

使用Agora.io Web SDK（AgoraRTC_N-4.16.1.js）构建视频聊天应用时，WebSocket在建立连接前持续失败，错误触发于SDK文件内。回滚SDK版本后问题依旧。

核心业务代码如下：

let joinAndDisplayLocalStream = async () => {
    client.on('user-published', () => {
        console.log("user has joined the room")
    })
    await client.join(APP_ID, CHANNEL, TOKEN, UID)

    localTracks = await AgoraRTC.createMicrophoneAndCameraTracks()

    let player = `<div class="video-container" id="user-container-${UID}">
                        <div class="username-wrapper"><span class="user-name">My Name</span></div>
                        <div class="video-player" id="user-${UID}"></div>
                    </div>`
    
    document.getElementById('video-streams').insertAdjacentHTML('beforeend', player)

    localTracks[1].play(`user-${UID}`) 

    await client.publish(localTracks[0], localTracks[1])
}

可能的原因 #

• 网络环境拦截：所在网络（如公司内网、校园网）的防火墙或代理服务器拦截了WebSocket请求，Agora默认使用443端口，部分严格环境可能限制非标准业务端口，可切换公共网络测试验证。
• Token参数异常：TOKEN无效、过期，或者生成Token时使用的UID、CHANNEL与代码中传入的参数不匹配，无效Token会直接导致连接Agora服务器失败。
• APP_ID配置错误：填写的APP_ID不正确，或者该APP_ID未完成Agora控制台的实名认证流程，导致服务被限制无法正常连接。
• HTTP环境限制：Agora Web SDK要求部署在HTTPS环境（localhost开发环境除外），如果网页运行在HTTP环境下，浏览器会阻止WebSocket连接请求。
• 媒体权限未获取：用户拒绝了麦克风/摄像头权限，即使代码调用了createMicrophoneAndCameraTracks，权限缺失可能间接导致后续连接流程异常，可检查浏览器控制台的权限报错信息。
• 跨域配置遗漏：网页域名未添加到Agora控制台的允许跨域列表中，触发浏览器跨域拦截，导致WebSocket连接失败。

内容的提问来源于stack exchange，提问作者Dennis Mathew Jose