用户反馈的黑屏复现不了

上线后陆续收到"视频播到一半黑屏"的反馈,本地怎么都复现不了。把日志串起来才看明白:弱网下加载失败,错误回调里没有处理,播放器停在一个尴尬的中间态,界面还显示"播放中",画面当然是黑的。这不是播放器的问题,是我们没有按状态机的规矩使用它。这篇把 AVPlayer 的状态流转梳理清楚。

▲ 示意图 · AVPlayer状态机

状态机是唯一的规矩

AVPlayer 的每个操作都只能在特定状态下调用,跳步骤调用就是各种诡异问题的来源。先记住主链路:idle → initialized → prepared → playing / paused → completed → released。

import { media } from '@kit.MediaKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function createPlayer(url: string): Promise<media.AVPlayer> {
  const player = await media.createAVPlayer(); // 初始 idle

  player.on('stateChange', (state: string) => {
    if (state === 'prepared') {
      player.play(); // 只有 prepared 之后才能 play
    }
  });

  player.on('error', (err: BusinessError) => {
    // 网络中断、格式不支持都走这里,必须处理
    console.error(`播放错误 code=${err.code}`);
    this.showErrorAndStop();
  });

  // idle 状态下赋值 url,进入 initialized
  player.url = url;
  // initialized 之后才能 prepare
  await player.prepare(); // → prepared
  return player;
}

三个状态规则最容易出事。url 只能在 idle 状态赋值,重复赋值直接抛错,换视频要先 reset() 回 idle。seek 只能在 prepared、playing、paused、completed 状态调,play 要等 prepared。很多"偶现黑屏"就是时序问题:界面显示播放按钮可点,但播放器还停在 initialized,用户一点就是错误。

错误处理决定观感

黑屏事件的根因就是错误回调是空的。播放器的错误五花八门:网络断开、证书问题、解码失败、源失效,但界面层的处理可以统一成一套:停止播放、展示可重试的提示、记录日志上报。注意 reset() 之前先把事件监听摘掉或确保幂等,否则重试创建新实例后旧监听还挂着,一次错误触发两次提示。

private releasePlayer(): void {
  this.player?.off('stateChange');
  this.player?.off('error');
  this.player?.release(); // 用完必须释放,泄漏是累积性的
  this.player = null;
}

release 这一步是内存泄漏的重灾区。列表页里每个视频项都创建播放器,滑出屏幕不释放,滑十几屏内存就涨到系统回收,然后整页卡死。规矩是实例和界面同生命周期,组件销毁必释放。

seek 与进度条

进度条拖动是高频操作,也有讲究。拖动过程中不要实时 seek,每秒能触发几十次,解码跟不上就卡顿。正确做法是拖动时只更新进度条的显示值,松手时 seek 一次。播放中拿进度用 currentTime 配合定时刷新,刷新间隔两百到五百毫秒足够,别用每帧回调去读。

另一个容易忽略的状态是 completed。播完之后进度条停在末尾,用户点重播要先 seek(0) 再 play,直接调 play 在部分场景行为不明确,显式回零最稳。

弱网与后台

视频场景要预设弱网的存在。加载中要有缓冲指示,长时间无数据要有超时处理,网络切换(Wi-Fi 到流量)触发错误后自动尝试恢复一次,恢复不了再交给用户。应用切后台时按产品语义处理:短视频类通常暂停,挂后台继续播音频的要转音频模式并接长时任务,这个在后台任务那篇讲过,两套机制配合使用。

写在最后

这次梳理把播放器的问题归成了三类:状态机违规调用,靠严格按状态写代码消灭;错误回调缺失,靠统一的错误处理兜底;实例泄漏,靠生命周期绑定解决。黑屏问题修完之后,同类反馈再没出现过,后来加了自动重试和清晰度切换,播放完成率还涨了五个点。媒体类功能的状态机看着繁琐,但它恰好是那种"第一次就写对,之后永远不用碰"的代码,值得在第一版就按规矩来。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐