Agora Web端上下行网络质量检测功能异常的重写优化方案咨询

原代码核心问题 #

• 初始值未设置：this.uplinkNetworkQuality和this.downlinkNetworkQuality没有预设初始值，首次触发回调时currentQuality为undefined，currentQuality < 4判断为false，首次检测到差网络不会触发提示
• 触发场景覆盖不全：仅支持网络从好(<4)变差(>=4)的单次触发，刚进入房间就处于差网络、网络持续处于差状态的场景都不会触发提示
• 多余类型转换：Agora返回的上下行质量值本身为数字类型，强制转字符串后parseInt可能产生NaN，导致判断逻辑失效
• 未处理异常值：没有过滤质量值为0（网络质量未知）的情况，会干扰正常判断

优化后代码 #

const rtcClient = this.client;
// 初始化网络质量默认值，1代表初始默认网络良好
this.uplinkNetworkQuality = this.uplinkNetworkQuality ?? 1;
this.downlinkNetworkQuality = this.downlinkNetworkQuality ?? 1;

// 差网络阈值可根据业务调整，Agora网络质量等级：0-未知 1-极好 2-好 3-一般 4-差 5-很差 6-极差
const BAD_QUALITY_THRESHOLD = 4;

const checkQualityStatus = (
  newQuality: number,
  currentQuality: number
): { newNetworkQuality: number; shouldShowBadTip: boolean } => {
  // 过滤未知质量的异常值
  const validNewQuality = newQuality === 0 ? currentQuality : newQuality;
  // 触发条件：当前新的有效质量 >= 阈值，且上一次状态未达到阈值（避免重复触发）
  const shouldShowBadTip = currentQuality < BAD_QUALITY_THRESHOLD && validNewQuality >= BAD_QUALITY_THRESHOLD;
  return { 
    newNetworkQuality: validNewQuality, 
    shouldShowBadTip 
  };
};

rtcClient.on('network-quality', (quality) => {
  if (typeof quality.uplinkNetworkQuality === 'number') {
    const {
      newNetworkQuality,
      shouldShowBadTip,
    } = checkQualityStatus(quality.uplinkNetworkQuality, this.uplinkNetworkQuality);

    if (shouldShowBadTip) {
      this._log('network-drop', { type: 'uplink', newNetworkQuality });
      // 此处添加触发用户侧慢网络提示的逻辑
      // showToast('您的上行网络不佳，可能导致直播卡顿')
    }

    this.uplinkNetworkQuality = newNetworkQuality;
  }

  if (typeof quality.downlinkNetworkQuality === 'number') {
    const {
      newNetworkQuality,
      shouldShowBadTip,
    } = checkQualityStatus(quality.downlinkNetworkQuality, this.downlinkNetworkQuality);

    if (shouldShowBadTip) {
      this._log('network-drop', { type: 'downlink', quality: newNetworkQuality });
      // 此处添加触发用户侧慢网络提示的逻辑
      // showToast('您的下行网络不佳，可能导致观看卡顿')
    }

    this.downlinkNetworkQuality = newNetworkQuality;
  }
});

优化说明 #

• 新增初始值兜底逻辑，避免首次判断失效
• 新增异常值过滤，排除网络质量未知的干扰
• 将阈值抽离为常量，方便后续业务调整
• 明确类型校验，避免非数字值导致的逻辑错误
• 保留单次触发逻辑：仅在网络从好变差的时候提示一次，避免频繁打扰用户，若需要持续提示可自行调整判断条件

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