在网页开发过程中，使用<video>标签嵌入视频时，经常会遇到视频无法正常加载播放的情况，这时候就需要通过合理的错误捕获和处理机制来解决问题，避免影响用户的使用体验。
HTML视频加载失败的常见原因
视频加载失败通常不是单一因素导致的，常见的触发原因主要有以下几类：
- 视频资源路径错误，比如文件路径拼写错误、资源被删除或者移动位置
- 视频格式不被浏览器支持，比如部分浏览器不支持特定的编码格式
- 网络异常导致资源请求失败，比如超时、断网或者服务器返回错误状态码
- 跨域资源访问限制，视频资源所在服务器没有配置对应的跨域许可
- 视频文件本身损坏，无法正常解析播放
onerror事件的基本用法
<video>标签的onerror事件会在视频加载过程中出现错误时触发，我们可以通过这个事件捕获错误相关信息，进而执行对应的处理逻辑。onerror事件触发时，会返回一个错误对象，其中code属性表示错误的类型，常见的错误码如下：
| 错误码 | 含义 |
|---|---|
| 1 | 用户主动终止了视频加载 |
| 2 | 网络错误导致视频加载失败 |
| 3 | 视频解码失败，可能是格式不支持或者文件损坏 |
| 4 | 视频资源无法找到，通常是路径错误 |
基础错误捕获示例
下面是一个最简单的onerror事件使用示例，当视频加载失败时，在控制台输出错误信息：
<video
src="test.mp4"
controls
onerror="handleVideoError(this)"
></video>
<script>
function handleVideoError(videoElement) {
// 获取错误对象
const error = videoElement.error;
if (error) {
console.log("视频加载失败，错误码：" + error.code);
console.log("错误信息：" + error.message);
}
}
</script>
常用的错误处理方法
1. 展示友好的错误提示
当视频加载失败时，直接给用户展示清晰的错误提示，比空白或者默认的错误样式体验更好：
<div id="videoErrorTip" style="display:none;color:#ff0000;padding:10px;">
视频加载失败，请刷新页面重试或者检查网络
</div>
<video
src="test.mp4"
controls
onerror="showErrorTip()"
></video>
<script>
function showErrorTip() {
document.getElementById("videoErrorTip").style.display = "block";
}
</script>
2. 切换备用视频资源
如果主视频资源加载失败，可以自动切换到备用的视频地址，提升资源可用性：
<video
id="mainVideo"
src="main.mp4"
controls
onerror="switchBackupVideo()"
></video>
<script>
function switchBackupVideo() {
const video = document.getElementById("mainVideo");
// 如果当前是主资源，切换到备用资源
if (video.src.indexOf("main.mp4") !== -1) {
video.src = "backup.mp4";
// 重新加载视频
video.load();
}
}
</script>
3. 错误日志上报
为了后续排查问题，可以把视频加载的错误信息上报到服务端：
function reportVideoError(videoElement) {
const error = videoElement.error;
if (!error) return;
const errorInfo = {
errorCode: error.code,
errorMsg: error.message,
videoSrc: videoElement.src,
pageUrl: window.location.href,
timestamp: new Date().getTime()
};
// 发送上报请求，这里假设上报接口地址为ipipp.com/report
fetch("https://ipipp.com/report", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify(errorInfo)
}).catch(e => {
console.log("错误上报失败：" + e.message);
});
}
注意事项
在使用onerror事件处理视频加载错误时，需要注意避免死循环问题，比如切换备用资源后如果备用资源也加载失败，会再次触发onerror事件，这时候需要添加判断逻辑，避免无限切换。另外，不同浏览器对视频格式的支持情况不同，建议提供多种格式的视频资源，通过<source>标签配置多个备选源，从源头减少加载失败的概率。
如果视频资源需要跨域访问，要确保资源服务器配置了正确的CORS响应头，否则即使路径正确，也可能因为跨域限制导致加载失败，这类错误同样会被onerror事件捕获，错误码通常为2或者3。
HTML_videoonerror事件视频加载失败错误处理修改时间：2026-07-02 09:15:28