Flutter使用agora_rtc_engine5.2.0时joinChannelSuccess未触发无报错

按以下优先级逐一排查，90%以上的场景都能定位解决：

• 事件注册顺序错误（最高发问题）
  5.x版本的事件回调是在注册监听器之后才会分发，必须在调用joinChannel方法前完成事件注册。很多开发者的错误写法是先调用加入频道，再绑定事件监听，此时加入成功的事件已经触发完毕，监听器根本无法收到。
  错误写法与正确写法参考：

  // ❌ 错误顺序：先加频道再注册事件，永远收不到回调
  final engine = createAgoraRtcEngine();
  await engine.initialize(RtcEngineContext(appId: 'YOUR_APPID'));
  await engine.joinChannel(token: token, channelId: channelId, uid: 0, options: ChannelMediaOptions());
  engine.registerEventHandler(RtcEngineEventHandler(
    joinChannelSuccess: (connection, elapsed) {
      // 回调永远不会执行
    },
  ));
  
  // ✅ 正确顺序：初始化引擎 -> 注册事件监听 -> 加入频道
  final engine = createAgoraRtcEngine();
  await engine.initialize(RtcEngineContext(appId: 'YOUR_APPID'));
  // 提前注册所有需要监听的事件
  engine.registerEventHandler(RtcEngineEventHandler(
    joinChannelSuccess: (connection, elapsed) {
      debugPrint('加入频道成功，频道ID：${connection.channelId}');
    },
    onError: (err, msg) {
      debugPrint('SDK抛出错误：错误码$err，信息$msg');
    },
  ));
  // 所有前置逻辑完成后再调用加入频道
  await engine.joinChannel(token: token, channelId: channelId, uid: 0, options: ChannelMediaOptions());
  

• 权限缺失导致流程静默卡住
  5.2.0版本在两端权限未授予的场景下，不会主动抛出错误，会直接卡在加入频道的流程中不返回任何回调：
  • Android端：确认AndroidManifest.xml中已添加必要权限，且Android 6.0及以上版本在调用加入频道前，已动态申请录音、摄像头（视频场景需要）权限：

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.CAMERA" /><!-- 纯音频场景可移除 -->
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    

  • iOS端：确认Info.plist中已添加麦克风、摄像头（视频场景需要）的权限描述，否则系统会拦截SDK的媒体采集流程，导致加入失败无回调：

    <key>NSMicrophoneUsageDescription</key>
    <string>需要麦克风权限完成音视频通话</string>
    <key>NSCameraUsageDescription</key>
    <string>需要摄像头权限完成视频通话</string><!-- 纯音频场景可移除 -->
    

• Token或入参不匹配无错误抛出
  5.2.0版本存在已知逻辑问题：当传入的Token格式非法、过期、与当前AppID/频道名/UID不匹配时，部分场景不会触发onError回调，也不会返回加入成功。排查时可先使用声网控制台生成的临时测试Token（不要用服务端签发的正式Token）测试，如果临时Token可以正常触发回调，说明是服务端签发Token的逻辑存在问题，常见错误为签发Token时传入的频道名、UID和客户端加入频道时传入的参数不一致。
• 引擎实例重复创建/事件监听器重复覆盖
  如果未调用release()销毁上一个RtcEngine实例就重复调用createAgoraRtcEngine()创建新实例，会出现事件分发异常，回调被旧实例抢占导致新实例收不到joinChannelSuccess。如果页面存在反复进入退出通话的逻辑，离开频道后不需要继续使用引擎时，必须按顺序执行销毁逻辑：

  await engine.leaveChannel();
  await engine.release();
  

  另外不要重复调用registerEventHandler，后注册的监听器会直接覆盖之前的监听器，如果新的监听器中未实现joinChannelSuccess回调，自然无法收到对应事件。
• 网络拦截导致SDK无法连接服务端
  如果以上配置都确认无误，可在初始化引擎时开启SDK日志，查看底层连接流程：

  await engine.initialize(RtcEngineContext(
    appId: 'YOUR_APPID',
    logConfig: LogConfig(
      level: LogLevel.logLevelInfo,
      filePath: '${(await getTemporaryDirectory()).path}/agora_sdk.log',
    ),
  ));
  

  如果日志中显示SDK持续重试连接节点失败，说明当前测试设备的网络存在拦截：常见为公司/校园网封禁了UDP端口、代理工具拦截了声网的接入请求，切换到普通4G/家用WiFi网络即可恢复。

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