HTML5视频播放错误码Error监控与用户提示逻辑-H5教程-PHP中文网

html5视频错误处理需映射error.code为可读提示、结合网络/设备上下文分级呈现并提供可操作建议：code=1不提示；code=2提示网络问题并加重试；code=3/4提示格式不支持并引导切换或fallback；需结合networkstate、progress、onstalled等信号精准归因，上报时必带currentsrc、effectivetype等上下文。

html5视频播放错误码error监控与用户提示逻辑

HTML5视频播放出错时，错误码（error.code）是定位问题的关键依据，但直接向用户展示数字码（如1、2、4）毫无意义。真正有效的做法是：**根据 error.code 映射可读原因 + 结合网络/设备上下文做分级提示 + 提供明确可操作的恢复建议**。

常见 error.code 含义与对应提示文案

video 元素的 error 事件中，video.error.code 是核心字段。主流浏览器支持以下标准值：

MediaError.MEDIA_ERR_ABORTED (1)：用户主动中断（如点击暂停后关闭标签页、跳转页面）。提示：“视频加载已取消”——无需重试，不打扰用户。
MediaError.MEDIA_ERR_NETWORK (2)：网络请求失败（404、500、超时、跨域拒绝等）。提示：“视频资源暂不可用，请检查网络或稍后重试”——可加“重试”按钮，触发 video.load() + video.play()。
MediaError.MEDIA_ERR_DECODE (3)：媒体解码失败（格式不支持、文件损坏、GPU解码异常）。提示：“当前设备暂不支持该视频格式”——建议切换清晰度（如有）、提示使用 Chrome/Firefox 等现代浏览器。
MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED (4)：src 属性指向的资源类型完全不被支持（如 IE 加载 .webm）。提示：“浏览器不支持此视频格式”——可自动 fallback 到备用 source 或提示更新浏览器。

增强判断：不能只看 error.code

单靠 code 容易误判。需结合其他信号提升准确性：

检查 video.networkState === HTMLMediaElement.NETWORK_NO_SOURCE，确认是否连 <source></source> 都没匹配成功；
监听 progress 事件是否长期无触发，再配合 code=2，可判定为弱网卡顿而非瞬时失败；
捕获 onstalled 事件持续 > 3s 且 buffered.length === 0，大概率是首帧加载失败，应归类为 network 问题并提示“视频尚未开始加载”；
在 iOS Safari 中，play() 被静音策略拦截时不会抛 error，但 video.readyState === 0 且 video.paused === true，需单独检测并提示“请手动点击播放并允许声音”。

用户提示策略：按影响程度分级呈现

避免弹窗轰炸，按场景选择反馈方式：

轻量级错误（code=1）：不提示，仅上报日志；
可恢复错误（code=2、部分 code=3）：在播放器内显示带「重试」按钮的底部 toast，3 秒自动消失；
终端性错误（code=4 或多次重试失败）：全屏遮罩层 + 清晰说明 + 「刷新页面」「切换线路」「联系客服」三选项；
静音/权限类问题（iOS/Android 特定）：首次出现时用气泡引导点击播放器控件，并记录用户是否已手动操作，避免重复提示。

监控上报：带上关键上下文才有效

上报错误日志时，仅传 error.code 毫无调试价值。务必附加：

video.currentSrc（实际请求地址，含参数和 cdn 域名）；
navigator.connection.effectiveType（如 '2g' / 'slow-2g'，判断是否弱网）；
video.videoWidth × video.videoHeight 和 video.buffered.end(0)（判断是否卡在首帧）；
自定义字段：playerMode: 'auto' | 'manual'、isMuted: video.muted、isIOS: /iPad|iPhone|iPod/.test(navigator.userAgent)。