HTML5 的<video>标签从被广泛支持到现在，已经算是前端里最"不起眼"的基础能力之一了。但有意思的是，我接触过的项目里，真正能把在线播放做稳、做全、做到用户不抱怨的，比例并不高。很多人以为写个<video src="xxx.mp4" controls>就完事了，结果上线之后陆续收到反馈：有的浏览器点了没反应、有的进度条拖不动、有的移动端点开就全屏、有的视频加载半天黑屏、还有的明明文件没问题却报格式不支持。这些问题单看都不复杂，凑在一起就变成了一个需要系统梳理的工程问题。
这篇内容我想把 HTML5 video 在线播放这件事从头到尾拆一遍。它适合刚接触前端音视频的同学，也适合已经用过<video>但被各种兼容性和体验问题折腾过的开发者。我会讲清楚<video>到底是怎么工作的、哪些属性是真正有用的、不同格式和编码该怎么选、自动播放为什么总是失败、移动端有哪些坑、以及怎么用原生 API 做一个体验过得去的自定义播放器。所有内容都围绕"在线播放"这个核心场景展开，不扯太远，尽量给到能直接抄作业的代码和配置。
1. 先把<video>当成一个状态机来理解
很多人用<video>出问题，根源在于把它当成一个"放视频的盒子"，而不是一个带状态的媒体对象。这个认知差异会直接影响你写代码的方式。一旦你把它理解成一个状态机，很多"莫名其妙"的现象就有了解释。
1.1 从加载到播放，元素到底经历了哪些阶段
一个<video>元素从出现在 DOM 里到真正播放出画面，中间会经过一系列状态变化。理解这些状态，是排查问题的第一步。核心状态大致可以这样划分：
| 状态 | 含义 | 常见触发 |
|---|---|---|
HAVE_NOTHING | 还没有任何媒体数据 | 刚创建元素 |
HAVE_METADATA | 元数据（时长、尺寸等）已就绪 | 收到首个数据包 |
HAVE_CURRENT_DATA | 当前播放位置有数据 | 可以显示当前帧 |
HAVE_FUTURE_DATA | 当前及后续有数据 | 可以开始播放 |
HAVE_ENOUGH_DATA | 数据足够流畅播放 | 缓冲充分 |
这些状态通过readyState属性读取，对应的常量挂在HTMLMediaElement上。实际开发中，最常打交道的是HAVE_METADATA（此时duration才有意义）和HAVE_ENOUGH_DATA（此时可以放心调用play()）。
我见过不少代码在loadedmetadata之前就去读video.duration，拿到的是NaN，然后进度条计算出错。这不是浏览器的 bug，而是你没等状态到位。正确的做法是监听loadedmetadata事件，在回调里再读取时长、初始化进度条。
const video = document.querySelector('video'); video.addEventListener('loadedmetadata', () => { console.log('时长:', video.duration); console.log('尺寸:', video.videoWidth, video.videoHeight); initProgressBar(video.duration); });这里有个细节值得说：duration在某些流式场景下可能是Infinity，尤其是没有明确时长信息的直播流。如果你的进度条逻辑假设duration一定是有限数字，就会出问题。所以初始化进度条前，最好加一个isFinite(video.duration)的判断。
1.2preload和src的加载时机，决定了首屏体验
preload属性控制浏览器在页面加载时对视频的预加载策略，取值有none、metadata、auto。这个属性的实际行为在不同浏览器上并不完全一致，但方向是一致的：
none：不主动加载，等用户操作。省流量，但点播放后要等。metadata：只加载元数据（时长、尺寸、首帧信息）。这是很多场景下的平衡点。auto：浏览器自行决定尽量多加载。首屏快，但费流量。
我的经验是：首屏就有多个视频的页面，一律用preload="metadata"，甚至none。因为浏览器对同时加载的媒体资源数量是有限制的，你放五六个preload="auto"的视频，结果就是谁都加载不完，首屏一片黑。而单个详情页的主视频，可以用auto换更快的起播。
还有一个容易被忽略的点：src的赋值时机。如果你在 HTML 里直接写src，浏览器解析到该标签就开始按preload策略加载。如果你用 JS 动态设置src，记得在设置后调用video.load()，否则某些情况下不会重新触发加载流程。
function switchSource(video, url) { video.src = url; video.load(); // 关键：通知浏览器重新加载 }提示：频繁切换
src时，先调用video.pause()再改src，可以避免一些浏览器在切换瞬间的异常报错。
1.3currentTime的读写不是即时生效的
拖动进度条本质是设置video.currentTime。但这里有个反直觉的地方：你设置currentTime之后，它不会立刻变成你设置的值，而是要等seeked事件触发后才真正到位。如果你在设置后马上读取，可能还是旧值。
video.currentTime = 30; video.addEventListener('seeked', () => { console.log('真正跳到了:', video.currentTime); }, { once: true });另外，在readyState还没到HAVE_METADATA时设置currentTime是无效的，浏览器会忽略。所以"点击某个时间点跳转"的功能，一定要确保元数据已加载。这个坑我在做章节跳转功能时踩过，用户点了章节没反应，查了半天才发现是元数据还没到位就设置了时间。
2. 格式与编码：为什么你的视频"格式不支持"
"格式不支持"是<video>相关反馈里出现频率最高的一类。但这句话本身是模糊的——用户说的"格式"和开发者理解的"格式"往往不是一回事。要讲清楚这个问题，得把容器格式和编码格式分开看。
2.1 容器不是编码，mp4后缀不代表一定能播
一个视频文件通常由两部分组成：容器（container）和编码（codec）。容器是"盒子"，编码是"盒子里装的东西"。.mp4只是容器格式，里面装的视频编码可能是 H.264，也可能是 H.265（HEVC），音频可能是 AAC，也可能是别的。
浏览器支持的是"容器 + 编码"的组合，而不是单纯看后缀。同样是.mp4，H.264 编码的基本全平台通吃，H.265 编码在很多浏览器上就播不了。这就是为什么有些视频在某个环境能播、换个环境就黑屏——文件后缀一样，里面的编码不一样。
当前主流浏览器对常见组合的支持情况，大致可以这样理解：
| 容器 | 视频编码 | 音频编码 | 兼容性评价 |
|---|---|---|---|
| MP4 | H.264 | AAC | 最稳，优先选 |
| WebM | VP9 | Opus | 现代浏览器良好 |
| WebM | VP8 | Vorbis | 兼容性不错 |
| Ogg | Theora | Vorbis | 较老，逐步淘汰 |
结论很直接：面向大众的在线播放，MP4 + H.264 + AAC 是默认答案。它不一定是最省带宽的，但兼容性最省心。WebM 可以作为补充源，但不要指望它单独扛起所有场景。
2.2 用<source>提供多源，让浏览器自己挑
<video>支持在内部放多个<source>，浏览器会按顺序挑选第一个它能播的。这是处理兼容性的标准做法：
<video controls preload="metadata" poster="cover.jpg"> <source src="movie.mp4" type="video/mp4; codecs=avc1.42E01E,mp4a.40.2"> <source src="movie.webm" type="video/webm; codecs=vp9,opus"> 你的浏览器不支持 HTML5 视频播放。 </video>注意type属性里的codecs参数。写上它，浏览器可以在不下载文件的情况下就判断能不能播，避免白白下载一个播不了的文件。这个细节对移动端流量用户尤其友好。
<source>的挑选逻辑是"第一个能播的就用"，所以顺序很重要：把兼容性最好的放前面。如果你把 WebM 放前面，某些老环境可能判断失误或者干脆跳过，反而增加不确定性。
2.3 编码参数里的那些"隐形杀手"
就算容器和编码大类都对了，编码参数不对照样出问题。我遇到过几次"文件是 H.264 但就是播不了"的情况，最后查出来是这些原因：
- Profile 过高：H.264 有 Baseline、Main、High 等 profile。High profile 在老设备上可能不支持，Baseline 兼容性最好但压缩率低。面向广泛设备时，Main 或适当配置的 High 是常见折中。
- 像素格式不对：有些工具导出的视频用了
yuv444p之类的像素格式，很多硬件解码器不支持，只认yuv420p。这个参数在转码时一定要显式指定。 - 关键帧间隔过大：关键帧（keyframe）间隔太大，会导致拖动进度条时定位慢、起播慢。在线播放场景下，关键帧间隔控制在 2 到 5 秒比较合适。
- 音频采样率异常：极少见但确实存在，某些非标准采样率会导致音频解码失败。
用命令行转码时，一个比较稳妥的在线播放配置大致是这样（以常见转码工具为例）：
# 转成兼容性优先的 MP4 ffmpeg -i input.mov \ -c:v libx264 -profile:v main -pix_fmt yuv420p \ -g 60 -keyint_min 60 \ -c:a aac -b:a 128k -ar 44100 \ -movflags +faststart \ output.mp4其中-movflags +faststart这个参数特别值得说。它把文件的索引信息（moov box）移到文件头部，这样浏览器不用下载完整个文件就能开始播放。没有这个参数，大文件可能要等很久才能起播，甚至一直转圈。这个参数是我做在线播放时必加的，属于"不加就等着被投诉"的级别。
3. 自动播放为什么总是失败，以及正确的应对姿势
自动播放（autoplay）是需求方最爱提、开发者最头疼的功能之一。几乎每个项目都会有人问"能不能打开就自动播"，然后你加了autoplay属性，发现有的环境能播、有的不能，还找不到规律。
3.1 自动播放的限制不是 bug，是策略
现代浏览器对带声音的自动播放普遍有严格限制。核心逻辑是：没有用户交互的情况下，不允许自动播放带声音的媒体。这是为了保护用户不被突然的声音打扰，属于产品策略层面的约束，不是技术缺陷。
所以你会看到这样的现象：桌面端某些环境下静音自动播放可以，带声音就不行；移动端几乎一律拦截带声音的自动播放。这不是你代码写错了，而是规则如此。
autoplay属性本身只是"请求自动播放"，浏览器有权拒绝。判断是否真的播起来了，要看play()返回的 Promise：
const playPromise = video.play(); if (playPromise !== undefined) { playPromise .then(() => { console.log('自动播放成功'); }) .catch((error) => { console.warn('自动播放被拦截:', error.name); // 这里要给出降级方案：显示播放按钮、提示用户点击 showPlayButton(); }); }play()返回 Promise 这个设计很关键，它让你能感知到播放是否真的开始了。很多老代码直接调用video.play()不处理返回值，结果就是"以为播了其实没播"，用户看到的是静止的首帧。
3.2 静音自动播放是当前最可靠的路径
如果你的场景确实需要"打开就动起来"（比如背景视频、产品展示页），最稳的方案是静音 + 自动播放 + 循环：
<video autoplay muted loop playsinline poster="cover.jpg"> <source src="bg.mp4" type="video/mp4"> </video>muted是关键。静音状态下，大多数浏览器允许自动播放。playsinline则是移动端的必需品，它告诉浏览器"在当前页面内播放，不要强制全屏"，后面讲移动端时会细说。
这里有个实操心得：muted属性在 HTML 里写上，有时候在某些动态创建元素的场景下不生效，保险起见在 JS 里也设置一次video.muted = true。我遇到过动态创建 video 元素时属性没生效的情况，加上这行就稳了。
3.3 用户交互后再播放，要抓住"手势"的时机
如果必须带声音播放，那就得等用户交互。但"用户交互"也有讲究：浏览器通常要求播放动作发生在用户手势的事件处理链里。也就是说，你可以在按钮的click回调里直接调用play()，但如果你在click里发了个异步请求，等请求回来再play()，这个"手势上下文"可能已经丢失了，播放照样被拦截。
// 可行：在 click 回调里同步调用 playButton.addEventListener('click', () => { video.play().catch(handlePlayError); }); // 有风险：异步之后手势上下文可能丢失 playButton.addEventListener('click', async () => { const url = await fetchVideoUrl(); // 异步等待 video.src = url; video.play(); // 可能被拦截 });如果确实需要异步准备，一个常见做法是：在用户点击时先播放一个极短的静音占位，或者先调用play()再切换源，尽量把播放动作保持在手势上下文内。这块没有银弹，得结合具体场景设计交互。
4. 移动端和自定义控件的那些坑
桌面端跑通不代表移动端没问题。移动端的浏览器行为差异更大，尤其是全屏、内联播放、控件这几块，坑特别集中。
4.1playsinline不写，iOS 上点开就全屏
在移动端，尤其是 iOS 的浏览器环境里，视频默认倾向于全屏播放。如果你做的是一个页面内嵌的小视频（比如信息流里的卡片视频），不加playsinline就会变成"点一下整个屏幕被视频占满"，体验很割裂。
<video playsinline webkit-playsinline controls> <source src="clip.mp4" type="video/mp4"> </video>webkit-playsinline是给一些老版本环境的兼容写法，和playsinline一起写上更保险。这个属性看起来不起眼，但它是移动端内联播放的前提，漏了它后面所有自定义控件的设计都白搭。
4.2 原生控件 vs 自定义控件，怎么选
controls属性会显示浏览器原生控件。原生控件的好处是零成本、行为符合平台习惯、无障碍支持好。坏处是样式不可控，各平台长得不一样，和你的设计稿对不上。
我的建议是分场景：
- 后台管理、内部工具、对样式没要求的场景：直接用
controls，省事。 - 面向用户的产品、有品牌设计要求的场景：隐藏原生控件（去掉
controls），自己做一套。
自定义控件不是简单画几个按钮，它要覆盖：播放/暂停、进度条（含缓冲进度）、音量、时间显示、全屏、可能还有倍速和画质切换。核心是把你对状态机的理解用上——所有控件的显示状态都要跟着video的事件走。
const video = document.querySelector('video'); const playBtn = document.querySelector('.play-btn'); const progress = document.querySelector('.progress'); playBtn.addEventListener('click', () => { if (video.paused) { video.play().catch(handlePlayError); } else { video.pause(); } }); video.addEventListener('play', () => { playBtn.classList.add('is-playing'); }); video.addEventListener('pause', () => { playBtn.classList.remove('is-playing'); }); video.addEventListener('timeupdate', () => { const percent = (video.currentTime / video.duration) * 100; progress.style.width = percent + '%'; });timeupdate事件的触发频率大约是每秒 4 次，用来更新进度条够用，但不要在里面做重计算，否则会拖累性能。如果要做更平滑的进度动画，可以用requestAnimationFrame在播放时读取currentTime。
4.3 缓冲状态和错误处理，别让用户对着黑屏猜
用户最怕的不是视频慢，而是"不知道发生了什么"。缓冲时给个 loading 提示，出错时给个明确的错误信息，这些细节决定了体验的下限。
video.addEventListener('waiting', () => { showLoading(); }); video.addEventListener('playing', () => { hideLoading(); }); video.addEventListener('error', () => { const err = video.error; const messages = { 1: '加载被中止', 2: '网络错误，请检查连接', 3: '视频解码失败，可能是格式问题', 4: '视频源不可用或格式不支持' }; showError(messages[err.code] || '播放出错'); });video.error.code的四个值对应不同的失败原因，把它们翻译成人话展示给用户，比干巴巴一个"播放失败"有用得多。尤其是 code 4，基本就是格式或源的问题，这时候可以提示用户"换个浏览器试试"或者自动降级到备用源。
注意：
error事件在<source>层面也可能触发。如果你用了多个<source>，要监听最后一个<source>的error事件来判断"所有源都失败了"，而不是只监听video的error。
5. 性能与体验：让在线播放真正"顺"
功能跑通只是及格线，在线播放的体验好坏，很大程度上取决于加载策略和资源处理。这一块做得好不好，用户感受非常直接。
5.1 首帧和封面图，决定了"第一印象"
视频在真正播放前，用户看到的是封面（poster）。如果没设poster，很多浏览器显示的是黑屏或者第一帧。黑屏给人的感觉就是"卡住了"。
poster建议用一张和视频首帧接近、体积小的图片。它不需要高清，因为只是占位。但一定要有，这是成本最低的体验提升。
<video poster="cover.webp" preload="metadata" playsinline controls> <source src="movie.mp4" type="video/mp4"> </video>另外，preload="metadata"配合poster，可以让页面在只加载少量数据的情况下就展示出完整的信息（封面 + 时长），用户点击后再加载实际内容。这个组合是我在列表页、详情页里最常用的配置。
5.2 大文件、长视频，靠分段和索引优化
一个几百 MB 的视频文件，如果让浏览器从头下载，起播会非常慢。前面提到的+faststart解决的是"索引在文件头"的问题，让浏览器能快速拿到元数据。但真正要流畅拖动、快速定位，还需要服务端支持按字节范围请求（Range 请求）。
Range 请求是 HTTP 层面的能力，浏览器在播放视频时会自动带上Range头，请求文件的某一段。服务端如果支持返回206 Partial Content，浏览器就能边下边播、拖动时只请求目标位置附近的数据。如果服务端不支持 Range，浏览器只能整个文件下载，长视频体验会非常差。
这个点经常被忽略，因为它是服务端配置，前端感知不到。但如果你发现"视频能播但进度条拖不动"或者"拖动后要等很久"，八成是服务端没开 Range 支持。排查方法很简单：打开开发者工具看网络请求，正常播放时应该能看到状态码 206 的分段请求，如果全是 200 的完整请求，那就是服务端的问题。
5.3 多个视频同屏，别让它们互相抢资源
信息流、商品列表这类页面经常一屏有好几个视频。如果每个都preload="auto"，浏览器会同时发起多个加载，带宽被瓜分，结果是谁都加载慢。
我的处理原则是：
- 列表里的视频统一
preload="none"，只显示封面。 - 用户点击某个视频时，才设置
src并load()。 - 同一时间只允许一个视频处于播放状态，播放新的之前先
pause()掉其他的。
function playExclusive(currentVideo, allVideos) { allVideos.forEach((v) => { if (v !== currentVideo && !v.paused) { v.pause(); } }); currentVideo.play().catch(handlePlayError); }这个"互斥播放"的逻辑看起来简单，但它是列表页体验的关键。用户滑动浏览时，如果好几个视频同时出声，那体验是灾难性的。
5.4 内存与资源释放，单页应用里尤其要注意
在单页应用里，路由切换后如果<video>元素还被引用着，它占用的内存和网络连接不会自动释放。时间长了，页面会越来越卡。
一个稳妥的做法是：组件卸载时，先pause()，再把src置空并load()，强制释放资源。
function disposeVideo(video) { video.pause(); video.removeAttribute('src'); video.load(); // 触发资源释放 }removeAttribute('src')之后再load()，是让浏览器清空当前媒体资源的标准做法。只pause()是不够的，资源还挂在那里。这个细节在长列表、频繁切换的场景里，对内存的影响很明显。
6. 排查在线播放问题的通用思路
最后分享一套我排查 video 问题的顺序，基本能覆盖大部分情况。遇到"播不了"，别急着改代码，按这个链路走一遍，定位会快很多。
6.1 从"文件本身"开始，而不是从代码开始
第一步永远是确认文件本身没问题。把视频文件单独拖进浏览器打开，如果能播，说明文件和环境没问题，问题在你的页面代码或服务端配置；如果单独打开也播不了，那就是文件编码或格式的问题，改代码没用。
这一步能省掉大量无效排查。我见过太多人一上来就怀疑自己的 JS 写错了，结果折腾半天发现是视频编码不对。
6.2 看网络请求，区分"加载问题"和"解码问题"
打开开发者工具的网络面板，观察视频请求：
- 请求失败（4xx、5xx）：服务端或路径问题。
- 请求成功但一直 pending、加载很慢：带宽或服务端 Range 支持问题。
- 请求成功、文件下载完整，但画面不出来：解码或编码问题。
这三类问题的解决方向完全不同，先分清类别再动手。
6.3 用canPlayType做能力探测
如果需要在运行时判断某个格式能不能播，可以用canPlayType：
const video = document.createElement('video'); const support = video.canPlayType('video/mp4; codecs="avc1.42E01E, mp4a.40.2"'); // 返回值："probably" | "maybe" | ""返回值"probably"表示很可能支持，"maybe"表示可能支持，空字符串表示不支持。注意它只是"探测"，不是绝对保证，最终还是要以实际播放结果为准。但在做多源切换、格式降级时，这个 API 很有用。
6.4 常见问题速查表
把高频问题整理成一张表，方便对照：
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 黑屏无画面 | 编码不支持 / 首帧未加载 | 检查编码、加 poster |
| 有画面无声音 | 音频编码问题 / 被静音 | 检查音频编码、muted 状态 |
| 进度条拖不动 | 服务端不支持 Range | 看网络请求是否 206 |
| 自动播放失败 | 浏览器策略拦截 | 静音或等用户交互 |
| 移动端点开全屏 | 缺 playsinline | 补上 playsinline |
| 起播很慢 | 索引在文件尾 / 未分段 | 加 faststart、开 Range |
| 切换源后不播放 | 未调用 load() | 设置 src 后调 load() |
这张表不是穷举，但覆盖了绝大多数实际会遇到的情况。排查时先对号入座，能快速缩小范围。
我个人在实际项目里的体会是，HTML5 video 的难点从来不在"能不能播"，而在"在各种环境、各种网络、各种文件下都能稳定地播"。它考验的是你对状态、格式、平台差异的综合理解，而不是某个 API 会不会用。把上面这些点吃透，大部分在线播放的需求都能接得住。后续如果要做更复杂的场景，比如多码率自适应、字幕轨道、画中画，那是在这个基础之上再往上叠，底子打牢了，扩展起来才不慌。
