本文详解 Agora SDK 在 Android 端视频黑屏（音频正常、用户可成功入会）的典型成因，重点指出 enableVideo() 调用时机错误、setupLocalVideo() 与 startPreview() 顺序颠倒、SurfaceView 创建方式不规范等关键问题，并提供结构清晰、可直接运行的修复方案。
本文详解 agora sdk 在 android 端视频黑屏（音频正常、用户可成功入会）的典型成因，重点指出 `enablevideo()` 调用时机错误、`setuplocalvideo()` 与 `startpreview()` 顺序颠倒、surfaceview 创建方式不规范等关键问题，并提供结构清晰、可直接运行的修复方案。
Agora 视频黑屏但音频正常，是 Android 集成中极为常见的“伪连接”问题——表面看用户已成功加入频道（onJoinChannelSuccess 触发）、远端用户也可见（onUserJoined 触发），实则视频渲染链路在某个环节断裂。根据您提供的代码，问题根源并非网络或 Token，而在于 SDK 初始化与视频管线配置的时序与方式存在多处关键缺陷。
? 核心问题定位
enableVideo()调用过早且孤立
您在setupVideoSDKEngine()中创建引擎后立即调用agoraEngine.enableVideo()，但此时尚未设置任何本地/远程视频画布，也未启动预览。Agora 官方文档明确要求：enableVideo()必须在setupLocalVideo()之后、startPreview()之前调用，否则视频模块可能无法正确初始化。SurfaceView创建方式不安全
手动new SurfaceView(getBaseContext())并直接添加到布局，易导致生命周期错位、Z-order 冲突（尤其未调用setZOrderMediaOverlay(true)于本地视图）。正确做法是使用RtcEngine.CreateRendererView(context)—— 此方法内部已做兼容性处理，确保 Surface 生命周期与 SDK 同步。startPreview()位置错误
您在joinChannel()中才调用startPreview()，但该方法应在setupLocalVideo()之后、joinChannel()之前执行。否则，本地摄像头预览流无法及时推送到 SDK，导致本地画面黑屏；同时远端也可能因未收到有效视频流而无法解码渲染。setupRemoteVideo()缺少容错与复用逻辑
每次onUserJoined都新建SurfaceView并addView()，若用户重复加入或频道内有多人，将导致视图重叠、内存泄漏。应复用已有 View 或在加入前清理容器。
✅ 正确初始化流程（关键代码段）
遵循 Agora 最佳实践，修正后的核心初始化逻辑如下：
远程控制 Android 设备，支持截图、自动化操作手机 App 等功能。本应用使用 uiautomator2 作为底层框架，通过 ADB 连接设备，用户无需 Root（1）查看手机屏幕；（2）自动化操作手机 App；（3）远程安装/卸载应用……
private void initializeAgoraEngine() {
try {
// ✅ 正确顺序：创建引擎 → 启用视频 → 设置本地画布 → 启动预览 → 加入频道
rtcEngine = RtcEngine.create(getBaseContext(), "YOUR_APP_ID", mRtcEventHandler);
rtcEngine.enableVideo(); // 必须在 setupLocalVideo 之后、startPreview 之前！
// ✅ 使用官方推荐方式创建 RendererView
localSurfaceView = RtcEngine.CreateRendererView(getBaseContext());
localSurfaceView.setZOrderMediaOverlay(true); // 本地视图需置顶
FrameLayout localContainer = findViewById(R.id.local_video_container);
localContainer.addView(localSurfaceView);
// ✅ setupLocalVideo 必须在 enableVideo 之后
rtcEngine.setupLocalVideo(new VideoCanvas(localSurfaceView,
VideoCanvas.RENDER_MODE_FIT, 0));
// ✅ startPreview 必须在 setupLocalVideo 之后、joinChannel 之前
rtcEngine.startPreview();
// ✅ 加入频道（Token 可传 null 测试，生产环境务必传有效 Token）
rtcEngine.joinChannel(token, channelName, null, uid);
} catch (Exception e) {
Log.e("Agora", "Failed to init engine", e);
Toast.makeText(this, "SDK 初始化失败：" + e.getMessage(), Toast.LENGTH_LONG).show();
}
}? 布局建议（避免容器冲突）
XML 中两个视频容器应明确尺寸与层级关系，避免 layout_weight 在动态添加 SurfaceView 时引发测量异常：
<!-- activity_video_call.xml -->
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent">
<!-- 远端视图：铺满背景 -->
<FrameLayout
android:id="@+id/remote_video_container"
android:layout_width="match_parent"
android:layout_height="match_parent" />
<!-- 本地小窗：固定尺寸，置于右上角 -->
<FrameLayout
android:id="@+id/local_video_container"
android:layout_width="140dp"
android:layout_height="200dp"
android:layout_gravity="top|end"
android:layout_margin="16dp" />
</FrameLayout>⚠️ 其他关键注意事项
-
权限检查必须同步完成：
checkSelfPermission()应在onCreate()中立即执行，若缺失权限，requestPermissions()后需在onRequestPermissionsResult()中回调initializeAgoraEngine()，不可跳过权限直接初始化 SDK。 -
Token 动态生成时机：您的
generateToken()在网络请求回调中触发，但此时rtcEngine可能尚未创建。建议将 Token 获取逻辑前置，或确保引擎初始化完成后再 join。 -
资源释放严格配对：
onDestroy()中必须按leaveChannel()→stopPreview()→destroy()顺序释放，且避免在主线程阻塞调用RtcEngine.destroy()（您原代码中用子线程销毁是正确的）。 -
日志诊断必备：开启 Agora 日志（
rtcEngine.setLogFile()）并过滤agora关键字，重点关注video encoder started,remote video stream received等提示，快速定位是采集、编码、传输还是渲染环节失败。
通过以上修正，90% 以上的“黑屏但有声”问题可被根治。核心思想是：严格遵循 SDK 文档定义的视频管线时序，放弃手动管理 SurfaceView，拥抱官方封装的 CreateRendererView 和标准生命周期钩子。
