HTML5 标签不解析WebVTT,由浏览器媒体引擎原生支持;WebVTT文件须严格符合格式(首行WEBVTT、时间戳00:00:01.234 --> 00:00:04.567、UTF-8无BOM)、须为直接子元素且属性齐全(kind="subtitles"、src、srclang、label),服务端需返回Content-Type: text/vtt并处理CORS。

HTML5 的 <video></video> 标签本身不“解析”WebVTT 文件——它把这件事完全交给浏览器内核处理。真正起作用的是浏览器媒体引擎对 WebVTT 的原生支持,整个过程不经过 JavaScript 解析、不依赖 DOM 渲染管线,而是直接由媒体合成器(Media Compositor)读取并渲染字幕轨道。
WebVTT 文件必须严格合规,否则浏览器静默丢弃
浏览器内置的 WebVTT 解析器容错率为零。只要以下任一条件不满足,整条 <track></track> 就不会注册进 video.textTracks 列表,右键菜单里也不会出现该字幕选项:
- 首行必须是顶格、全大写、无空格、无缩进、无 BOM 的 WEBVTT(写成
webvtt、WebVTT或前面有空格/换行都会失败) - 时间戳格式强制为
00:00:01.234 --> 00:00:04.567:小时、分钟、秒均为两位,毫秒必须三位,箭头前后各一个空格,不能省略小时位(即使为 0) - 文件编码必须是 UTF-8 无 BOM;Windows 记事本默认带 BOM,务必用 VS Code、Sublime 或 Notepad++ 保存为 “UTF-8”(不是 “UTF-8 with BOM”)
- 中文、日文等非 ASCII 字符需直接写入,确保编辑器与服务器都按 UTF-8 解析,否则显示为方块或问号
<track></track> 必须放在正确位置且属性齐全
浏览器只在特定结构中识别轨道。它不是装饰性标签,而是语义化媒体轨道声明:
-
<track></track>必须是<video></video>的**直接子元素**,且必须紧接在所有<source></source>标签之后、之前 - 不能包在
<div> 里,不能写在 <code><source></source>前面,也不能出现在外面(哪怕多一个换行) - 四个属性缺一不可:
kind(必须为subtitles)、src(可访问的 .vtt 路径)、srclang(标准 BCP 47 语言码,如zh-Hans、en-US)、label(用户可见名称) - .vtt 文件必须由服务端返回
Content-Type: text/vtt - 若字幕文件跨域,还需服务端设置
Access-Control-Allow-Origin: *(或对应域名) - 本地开发时用 file:// 协议会触发 CORS 限制,建议用本地服务器(如 VS Code Live Server、Python -m http.server)测试
-
video.textTracks返回静态列表,每个轨道含kind、language、label、mode(disabled/hidden/showing)等属性 -
track.readyState === 2表示已加载完成(TextTrack.LOADED) - 可通过
track.mode = 'showing'主动启用,其余设为'disabled'实现语言切换
服务端响应必须匹配 MIME 类型
即使文件和 HTML 都写对了,如果服务器返回错误的 Content-Type,浏览器也会拒绝加载轨道:
立即学习“前端免费学习笔记(深入)”;
验证是否成功加载:用 textTracks API 检查
不要只看播放器控件栏——用代码确认轨道状态更可靠:



















