视频播到一半黑屏,鸿蒙 AVPlayer 状态机的一次梳理
用户反馈的黑屏复现不了
上线后陆续收到"视频播到一半黑屏"的反馈,本地怎么都复现不了。把日志串起来才看明白:弱网下加载失败,错误回调里没有处理,播放器停在一个尴尬的中间态,界面还显示"播放中",画面当然是黑的。这不是播放器的问题,是我们没有按状态机的规矩使用它。这篇把 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 到流量)触发错误后自动尝试恢复一次,恢复不了再交给用户。应用切后台时按产品语义处理:短视频类通常暂停,挂后台继续播音频的要转音频模式并接长时任务,这个在后台任务那篇讲过,两套机制配合使用。
写在最后
这次梳理把播放器的问题归成了三类:状态机违规调用,靠严格按状态写代码消灭;错误回调缺失,靠统一的错误处理兜底;实例泄漏,靠生命周期绑定解决。黑屏问题修完之后,同类反馈再没出现过,后来加了自动重试和清晰度切换,播放完成率还涨了五个点。媒体类功能的状态机看着繁琐,但它恰好是那种"第一次就写对,之后永远不用碰"的代码,值得在第一版就按规矩来。
更多推荐


所有评论(0)