微信小程序推流黑屏如何排查？

Question

问题：微信小程序推流黑屏如何排查？ 在使用微信小程序进行实时音视频推流时，常有开发者反馈出现“推流黑屏”问题。该问题表现为摄像头已开启、权限已授权，但推流画面为黑色或无图像显示。可能原因包括：前置/后置摄像头切换异常、canvas或video组件层级冲突、推流路径（url）无效、设备资源未正确释放、编码参数设置不合理，或真机调试时未关闭调试器导致渲染阻塞。此外，部分安卓机型存在兼容性问题，也会引发黑屏。需结合微信开发者工具日志、realtime-log日志及真机测试逐步排查，确认推流组件初始化顺序、权限状态与硬件访问是否正常。

Answer 1

一、现象描述与初步判断

微信小程序推流黑屏是音视频开发中较为典型的视觉异常问题。开发者常反馈：摄像头权限已开启，<live-pusher>组件正常初始化，控制台无明显报错，但画面始终为黑色或完全无图像输出。

• 用户端表现为“绿幕”或纯黑画面
• 音频推流正常，仅视频异常
• 部分机型复现率高（如华为Mate系列、小米Redmi Note系列）
• 开发者工具中显示正常，真机测试出现黑屏

此阶段应优先确认是否为环境误判，例如调试器未关闭导致canvas渲染阻塞，或模拟器本身不支持硬件编码。

二、排查路径分层模型

    ```mermaid
    graph TD
      A[推流黑屏] --> B{是否开发者工具可见?}
      B -- 是 --> C[检查真机调试模式]
      B -- 否 --> D[检查组件初始化顺序]
      C --> E[关闭vConsole调试面板]
      D --> F[验证权限与设备访问]
      F --> G[分析realtime-log日志]
      G --> H[检测编码参数兼容性]
      H --> I[适配特定安卓机型]
    ```
  

该流程图展示了从表象到内核的逐层下钻逻辑，适用于系统性故障定位。

三、常见技术原因与对应解决方案

分类	具体原因	检测方式	解决策略
权限配置	camera授权未获取或被拒绝	调用 wx.getSetting 检查 scope.camera	引导用户重新授权，使用 wx.authorize 请求权限
组件层级	video/canvas覆盖 live-pusher	审查wxml结构与z-index层级	调整视图栈顺序，确保推流组件在最底层
推流地址	rtmp url格式错误或服务器不可达	通过ping和ffplay验证url有效性	校验URL协议头、域名解析及推流密钥时效性
硬件资源	摄像头被其他应用占用	查看设备管理器或adb logcat日志	退出冲突应用，合理释放MediaRecorder实例
编码设置	分辨率超出设备能力（如4K@60fps）	读取realtime-log中的encoder_error事件	降级至720p@30fps并启用自适应码率
调试干扰	vConsole阻塞GPU线程	真机运行时观察底部调试浮窗	发布前关闭开发者工具“启用调试”选项
机型兼容	厂商定制ROM对WebGL限制	在华为/OPPO等设备抓取surfaceflinger日志	使用forceUseCamera2Api:true强制启用Camera2 API
初始化时机	页面加载未完成即启动推流	监听onReady回调状态	确保live-pusher绑定bindready后再执行start
前后置切换	switchCamera调用失败未捕获异常	添加catch回调打印error.code	延迟切换+重试机制+默认后置摄像头
内存泄漏	频繁创建销毁live-pusher导致GPU上下文丢失	监控FPS下降与内存增长趋势	单例模式管理推流组件，避免重复挂载

四、深入日志分析方法

微信小程序提供realtime-log接口用于捕获底层媒体引擎行为。可通过如下代码注入日志监听：

// 在App.onLaunch中注册实时日志
const logger = wx.getRealtimeLogManager ? wx.getRealtimeLogManager() : null;

if (logger) {
  logger.info('live-pusher init');
  logger.warn('potential encoder issue');
}

// 在live-pusher binderror中上报
Page({
  onError: function(e) {
    logger.error('pusher error:', e.detail.errMsg);
    console.error('Push Error:', e.detail);
  }
});

重点关注以下日志关键词：camera_open_failed, encode_start_fail, texture_capture_timeout，这些通常指向硬件抽象层（HAL）交互异常。

五、典型安卓兼容性处理方案

部分国产安卓机型存在Camera1 API老化问题，需主动启用Camera2。可在WXML中显式声明：

<live-pusher
  id="pusher"
  url="{{pushUrl}}"
  mode="RTC"
  autopush
  enable-camera="{{true}}"
  auto-focus
  orientation="vertical"
  beauty="5"
  whiteness="3"
  force-use-camera2-api="{{true}}"
  bindready="onPusherReady"
  binderror="onError"
/>

同时，在JS层进行运行时检测：

const systemInfo = wx.getSystemInfoSync();
const isHuaweiEMUI = systemInfo.brand === 'huawei' && systemInfo.system.indexOf('EMUI') > -1;
const isOldAndroid = systemInfo.platform === 'android' && parseFloat(systemInfo.system.split(' ')[1]) < 10;

this.setData({
  forceUseCamera2Api: isHuaweiEMUI || isOldAndroid
});