如何实现音视频通话功能？使用agora_rtc_engine遇黑屏求解决方案

基础音视频通话实现步骤 #

• 集成依赖：在 pubspec.yaml 中添加 agora_rtc_engine: ^x.x.x（替换为最新稳定版本），执行 flutter pub get 完成依赖拉取
• 权限配置：
  • Android：在 AndroidManifest.xml 中添加相机、麦克风权限

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    

  • iOS：在 Info.plist 中添加权限描述

    <key>NSCameraUsageDescription</key>
    <string>需要访问相机进行视频通话</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>需要访问麦克风进行语音通话</string>
    

• 初始化引擎：

  RtcEngine engine = await RtcEngine.createWithContext(RtcEngineContext("你的AppID"));
  

• 开启视频模块：

  await engine.enableVideo();
  

• 设置本地视频视图：

  await engine.setupLocalVideo(VideoCanvas(
    uid: 0,
    view: SurfaceView(), // Android 可选 TextureView；iOS 使用 AgoraVideoView
  ));
  

• 加入通话频道：

  await engine.joinChannel("你的Token", "频道名称", null, 0);
  

• 监听远程用户并设置远程视图：

  engine.setEventHandler(RtcEngineEventHandler(
    userJoined: (int uid, int elapsed) {
      engine.setupRemoteVideo(VideoCanvas(
        uid: uid,
        view: SurfaceView(),
      ));
    },
  ));
  

首次连接后持续黑屏的解决方案 #

1. 检查视图生命周期与引用 #

• 确保远程视频视图未被意外销毁或隐藏，比如在 StatefulWidget 的 setState 操作中，避免错误重建视图导致引擎丢失渲染引用
• 用户离开频道后需调用 setupRemoteVideo 清空视图，重新加入频道时必须再次调用该方法绑定新的渲染视图

2. 排查视频流状态 #

• 监听 remoteVideoStateChanged 事件，获取视频流状态与异常原因：

  remoteVideoStateChanged: (int uid, VideoState state, VideoStateReason reason, int elapsed) {
    print("远程视频状态：$state，异常原因：$reason");
  },
  

  • 若状态为 VideoStateFailed，根据 reason 定位：比如网络波动导致流中断、对方设备相机被其他应用占用

3. 验证引擎配置与权限 #

• 确认加入频道前已调用 enableVideo()，若中途关闭过视频模块，重新开启后需重新设置视图
• Android 6.0+ 需动态申请相机权限，确保权限已被用户授予；iOS 需确认系统设置中已允许应用访问相机
• 避免在应用后台强制渲染视频，部分系统会限制后台相机使用，导致画面黑屏

4. 修复视图渲染问题 #

• 尝试替换渲染视图类型：Android 端将 SurfaceView 换成 TextureView，iOS 端检查 AgoraVideoView 的布局约束是否合理
• 确保视频视图的宽高不为0，使用 Expanded、AspectRatio 或固定宽高约束保证视图正常渲染

5. 版本兼容性排查 #

• 升级 agora_rtc_engine 到最新稳定版本，旧版本可能存在已知的渲染bug
• 确认 Flutter 版本与插件版本兼容，比如 Flutter 3.x 需使用适配的插件版本

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